1use std::{
19 num::{NonZeroU32, NonZeroUsize},
20 str::FromStr,
21 sync::{
22 Arc,
23 atomic::{AtomicBool, AtomicU32, 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, FundingRatesResponse,
38 InstrumentResponse, InstrumentsResponse, RequestBars, RequestBookSnapshot,
39 RequestCustomData, RequestFundingRates, RequestInstrument, RequestInstruments,
40 RequestTrades, SubscribeBars, SubscribeBookDeltas, SubscribeBookDepth,
41 SubscribeCustomData, SubscribeFundingRates, SubscribeIndexPrices, SubscribeInstrument,
42 SubscribeInstruments, SubscribeMarkPrices, SubscribeQuotes, SubscribeTrades,
43 TradesResponse, UnsubscribeBars, UnsubscribeBookDeltas, UnsubscribeBookDepth,
44 UnsubscribeCustomData, UnsubscribeFundingRates, UnsubscribeIndexPrices,
45 UnsubscribeMarkPrices, UnsubscribeQuotes, UnsubscribeTrades,
46 subscribe::SubscribeInstrumentStatus, unsubscribe::UnsubscribeInstrumentStatus,
47 },
48 },
49};
50use nautilus_core::{
51 AtomicMap, Params,
52 datetime::datetime_to_unix_nanos,
53 nanos::UnixNanos,
54 time::{AtomicTime, get_atomic_clock_realtime},
55};
56use nautilus_live::{
57 SocketControlFactory,
58 task::{TaskGroup, TaskGroupGuard, TaskSpawner},
59};
60use nautilus_model::{
61 data::{
62 BookOrder, CustomData, Data, DataType, OrderBookDelta, OrderBookDeltas, QuoteTick,
63 depth::DEPTH10_LEN,
64 },
65 enums::{
66 AggregationSource, BookAction, BookType, MarketStatusAction, OrderSide, PriceType,
67 RecordFlag,
68 },
69 identifiers::{ClientId, InstrumentId, Venue},
70 instruments::{Instrument, InstrumentAny},
71 types::{Price, Quantity},
72};
73use parking_lot::Mutex;
74use rust_decimal::Decimal;
75use tokio_util::sync::CancellationToken;
76use ustr::Ustr;
77
78use crate::{
79 book::{
80 BinanceBookError,
81 pacing::{SnapshotPacer, SnapshotPermit},
82 recovery::spawn_recovery,
83 sync::{BookSyncTracker, DepthSequencing, DepthSnapshot, DepthUpdate},
84 },
85 common::{
86 bar::{binance_bar_data_type, binance_bars_to_custom_data, parse_binance_bar_type},
87 consts::{
88 BINANCE_BOOK_DEPTHS, BINANCE_PARTIAL_BOOK_DEPTH, BINANCE_VENUE,
89 BINANCE_WS_HEARTBEAT_SECS,
90 },
91 enums::{BinanceEnvironment, BinanceProductType},
92 http_weights::depth_weight_futures as depth_request_weight,
93 parse::{
94 bar_spec_to_binance_interval, parse_millis, parse_millis_or_init,
95 parse_price_at_precision, parse_quantity_at_precision,
96 parse_required_price_at_precision, parse_required_quantity_at_precision,
97 quote_to_l1_deltas,
98 },
99 status::diff_and_emit_statuses,
100 symbol::{format_binance_stream_symbol, format_binance_symbol},
101 urls::{get_usdm_ws_route_base_url, get_ws_public_base_url},
102 websocket::{chain_command, send_book_snapshot},
103 },
104 config::BinanceDataClientConfig,
105 data_types::{
106 BinanceFuturesLiquidation, BinanceFuturesOpenInterest, BinanceFuturesOpenInterestHist,
107 BinanceFuturesOpenInterestHistPoint, register_binance_custom_data,
108 },
109 futures::{
110 http::{
111 client::{BinanceFuturesHttpClient, BinanceFuturesInstrument},
112 error::BinanceFuturesHttpError,
113 models::BinanceOrderBook,
114 query::{BinanceDepthParams, BinanceOpenInterestHistParams, BinanceOpenInterestParams},
115 },
116 websocket::streams::{
117 client::BinanceFuturesWebSocketClient,
118 messages::BinanceFuturesWsStreamsMessage,
119 parse_data::{
120 parse_agg_trade, parse_book_ticker, parse_depth_snapshot, parse_depth_update,
121 parse_kline, parse_mark_price, parse_ticker, parse_trade,
122 },
123 },
124 },
125};
126
127const MARKET_STREAMS_ENDPOINT: &str = "binance-futures-market-streams";
128const PUBLIC_STREAMS_ENDPOINT: &str = "binance-futures-public-streams";
129
130const SNAPSHOT_WEIGHT_PER_MINUTE: NonZeroU32 = NonZeroU32::new(1_200).expect("non-zero");
132
133#[derive(Debug)]
135pub struct BinanceFuturesDataClient {
136 clock: &'static AtomicTime,
137 client_id: ClientId,
138 config: BinanceDataClientConfig,
139 product_type: BinanceProductType,
140 http_client: BinanceFuturesHttpClient,
141 ws_client: BinanceFuturesWebSocketClient,
142 ws_public_client: BinanceFuturesWebSocketClient,
143 data_sender: EventSender<DataEvent>,
144 is_connected: AtomicBool,
145 cancellation_token: CancellationToken,
146 session_tasks: TaskGroup,
147 command_tasks: TaskGroup,
148 shutdown_errors: Vec<String>,
149 instruments: Arc<AtomicMap<InstrumentId, InstrumentAny>>,
150 status_cache: Arc<AtomicMap<InstrumentId, MarketStatusAction>>,
151 instrument_update_lock: Arc<tokio::sync::Mutex<()>>,
152 book_sync: BookSyncTracker,
153 book_subscriptions: Arc<AtomicMap<InstrumentId, u32>>,
154 book_deltas: AHashSet<InstrumentId>,
155 book_depths: Arc<AtomicMap<InstrumentId, usize>>,
156 book_unsubscribes_pending: Arc<AtomicMap<InstrumentId, Vec<BookDrain>>>,
157 l1_book_subscriptions: Arc<AtomicMap<InstrumentId, u32>>,
158 quote_refs: Arc<AtomicMap<InstrumentId, u32>>,
159 mark_price_refs: Arc<AtomicMap<InstrumentId, u32>>,
161 ticker_refs: Arc<AtomicMap<InstrumentId, u32>>,
162 force_order_refs: Arc<AtomicMap<InstrumentId, u32>>,
163 force_order_all_market_refs: Arc<AtomicU32>,
164 force_order_all_market_stream_active: Arc<AtomicBool>,
165 force_order_ws_lock: Arc<tokio::sync::Mutex<()>>,
166 book_command_tail: Arc<Mutex<Option<tokio::sync::oneshot::Receiver<()>>>>,
167 book_drain_generation: u64,
168}
169
170impl BinanceFuturesDataClient {
171 pub fn new(
178 client_id: ClientId,
179 config: BinanceDataClientConfig,
180 product_type: BinanceProductType,
181 ) -> anyhow::Result<Self> {
182 config.validate()?;
183
184 match product_type {
185 BinanceProductType::UsdM | BinanceProductType::CoinM => {}
186 _ => {
187 anyhow::bail!(
188 "BinanceFuturesDataClient requires UsdM or CoinM product type, was {product_type:?}"
189 );
190 }
191 }
192
193 let clock = get_atomic_clock_realtime();
194 let data_sender = get_data_event_sender();
195 let socket_factory = SocketControlFactory::new(client_id, Some(*BINANCE_VENUE));
196 let api_key = config
197 .api_key
198 .as_ref()
199 .map(|value| value.expose_secret().to_owned());
200 let api_secret = config
201 .api_secret
202 .as_ref()
203 .map(|value| value.expose_secret().to_owned());
204 let proxy_url = config
205 .proxy_url
206 .as_ref()
207 .map(|value| value.expose_secret().to_owned());
208
209 let http_client = BinanceFuturesHttpClient::new(
210 product_type,
211 config.environment,
212 clock,
213 api_key.clone(),
214 api_secret.clone(),
215 config.base_url_http.clone(),
216 Some(config.recv_window_ms),
217 None, proxy_url.clone(),
219 false, )?
221 .with_retry_config(config.retry_config());
222
223 let market_url = config.base_url_ws.clone().map(|url| {
224 if product_type == BinanceProductType::UsdM
225 && config.environment == BinanceEnvironment::Live
226 {
227 get_usdm_ws_route_base_url(&url, "market")
228 } else {
229 url
230 }
231 });
232
233 let ws_client = BinanceFuturesWebSocketClient::new(
234 product_type,
235 config.environment,
236 api_key,
237 api_secret,
238 market_url,
239 Some(BINANCE_WS_HEARTBEAT_SECS),
240 config.transport_backend,
241 )?
242 .with_proxy(proxy_url.clone())
243 .with_socket_control(socket_factory.clone(), MARKET_STREAMS_ENDPOINT);
244
245 let public_url = config.base_url_ws.clone().map_or_else(
246 || get_ws_public_base_url(product_type, config.environment).to_string(),
247 |url| {
248 if product_type == BinanceProductType::UsdM
249 && config.environment == BinanceEnvironment::Live
250 {
251 get_usdm_ws_route_base_url(&url, "public")
252 } else {
253 url
254 }
255 },
256 );
257
258 let ws_public_client = BinanceFuturesWebSocketClient::new(
259 product_type,
260 config.environment,
261 None,
262 None,
263 Some(public_url),
264 Some(BINANCE_WS_HEARTBEAT_SECS),
265 config.transport_backend,
266 )?
267 .with_proxy(proxy_url)
268 .with_socket_control(socket_factory, PUBLIC_STREAMS_ENDPOINT);
269
270 let snapshot_pacer = Arc::new(SnapshotPacer::new(SNAPSHOT_WEIGHT_PER_MINUTE));
271
272 let book_sync = BookSyncTracker::new(
273 DepthSequencing::Futures,
274 data_sender.clone(),
275 snapshot_pacer,
276 );
277
278 let session_tasks = TaskGroup::new();
279 let command_tasks = TaskGroup::new();
280
281 Ok(Self {
282 clock,
283 client_id,
284 config,
285 product_type,
286 http_client,
287 ws_client,
288 ws_public_client,
289 data_sender,
290 is_connected: AtomicBool::new(false),
291 cancellation_token: session_tasks.cancellation_token(),
292 session_tasks,
293 command_tasks,
294 shutdown_errors: Vec::new(),
295 instruments: Arc::new(AtomicMap::new()),
296 status_cache: Arc::new(AtomicMap::new()),
297 instrument_update_lock: Arc::new(tokio::sync::Mutex::new(())),
298 book_sync,
299 book_subscriptions: Arc::new(AtomicMap::new()),
300 book_deltas: AHashSet::new(),
301 book_depths: Arc::new(AtomicMap::new()),
302 book_unsubscribes_pending: Arc::new(AtomicMap::new()),
303 l1_book_subscriptions: Arc::new(AtomicMap::new()),
304 quote_refs: Arc::new(AtomicMap::new()),
305 mark_price_refs: Arc::new(AtomicMap::new()),
306 ticker_refs: Arc::new(AtomicMap::new()),
307 force_order_refs: Arc::new(AtomicMap::new()),
308 force_order_all_market_refs: Arc::new(AtomicU32::new(0)),
309 force_order_all_market_stream_active: Arc::new(AtomicBool::new(false)),
310 force_order_ws_lock: Arc::new(tokio::sync::Mutex::new(())),
311 book_command_tail: Arc::new(Mutex::new(None)),
312 book_drain_generation: 0,
313 })
314 }
315
316 fn venue(&self) -> Venue {
317 *BINANCE_VENUE
318 }
319
320 fn send_data(sender: &EventSender<DataEvent>, data: Data) {
321 if let Err(e) = sender.send(DataEvent::Data(data)) {
322 log::error!("Failed to emit data event: {e}");
323 }
324 }
325
326 fn spawn_ws<F>(&self, fut: F, context: &'static str)
327 where
328 F: Future<Output = anyhow::Result<()>> + Send + 'static,
329 {
330 let future = async move {
331 if let Err(e) = fut.await {
332 log::error!("{context}: {e:?}");
333 }
334 };
335
336 if let Err(e) = self.command_tasks.spawn(future) {
337 log::warn!("Skipping Binance Futures {context} after shutdown began: {e}");
338 }
339 }
340
341 fn spawn_command<F>(&self, future: F)
342 where
343 F: Future<Output = ()> + Send + 'static,
344 {
345 if let Err(e) = self.command_tasks.spawn(future) {
346 log::warn!("Skipping Binance Futures data command after shutdown began: {e}");
347 }
348 }
349
350 async fn finish_tasks(&self) -> anyhow::Result<()> {
351 let (session_result, command_result) = tokio::join!(
352 self.session_tasks
353 .finish_shutdown(Duration::from_secs(1), Duration::from_secs(2)),
354 self.command_tasks
355 .finish_shutdown(Duration::from_secs(1), Duration::from_secs(2)),
356 );
357 let mut errors = Vec::new();
358 if let Err(e) = session_result {
359 errors.push(format!(
360 "failed to finish Binance Futures data session tasks: {e}"
361 ));
362 }
363
364 if let Err(e) = command_result {
365 errors.push(format!(
366 "failed to finish Binance Futures data command tasks: {e}"
367 ));
368 }
369
370 if !errors.is_empty() {
371 anyhow::bail!(errors.join("; "));
372 }
373 Ok(())
374 }
375
376 async fn prepare_task_groups(&mut self) -> anyhow::Result<()> {
377 if !self.session_tasks.is_open() || !self.command_tasks.is_open() {
378 self.teardown_partial_connect().await?;
379 self.session_tasks
380 .start_generation()
381 .context("failed to start Binance Futures data session task generation")?;
382 self.command_tasks
383 .start_generation()
384 .context("failed to start Binance Futures data command task generation")?;
385 self.cancellation_token = self.session_tasks.cancellation_token();
386 }
387 Ok(())
388 }
389
390 async fn teardown_partial_connect(&mut self) -> anyhow::Result<()> {
391 self.session_tasks.begin_shutdown();
392 self.command_tasks.begin_shutdown();
393 self.ws_client.begin_shutdown();
394 self.ws_public_client.begin_shutdown();
395
396 if let Err(e) = self.ws_client.close().await {
397 self.shutdown_errors
398 .push(format!("market WebSocket close failed: {e}"));
399 }
400
401 if let Err(e) = self.ws_public_client.close().await {
402 self.shutdown_errors
403 .push(format!("public WebSocket close failed: {e}"));
404 }
405
406 if let Err(e) = self.finish_tasks().await {
407 self.shutdown_errors.push(e.to_string());
408 }
409 self.is_connected.store(false, Ordering::Release);
410
411 if !self.shutdown_errors.is_empty() {
412 let errors = std::mem::take(&mut self.shutdown_errors);
413 anyhow::bail!(
414 "Binance Futures data teardown failed: {}",
415 errors.join("; ")
416 );
417 }
418 Ok(())
419 }
420
421 #[expect(clippy::too_many_arguments)]
422 async fn refresh_instrument_catalog(
423 http: &BinanceFuturesHttpClient,
424 provider: &crate::config::BinanceInstrumentProviderConfig,
425 instruments_cache: &Arc<AtomicMap<InstrumentId, InstrumentAny>>,
426 status_cache: &Arc<AtomicMap<InstrumentId, MarketStatusAction>>,
427 instrument_update_lock: &tokio::sync::Mutex<()>,
428 ws: &BinanceFuturesWebSocketClient,
429 ws_public: &BinanceFuturesWebSocketClient,
430 sender: &EventSender<DataEvent>,
431 clock: &'static AtomicTime,
432 emit_status_changes: bool,
433 ) -> anyhow::Result<Vec<InstrumentAny>> {
434 let _guard = instrument_update_lock.lock().await;
435 let instruments = http
436 .request_instruments_with_config(provider)
437 .await
438 .context("failed to request Binance Futures instruments")?;
439 let venue_statuses = http
440 .request_symbol_statuses()
441 .await
442 .context("failed to request Binance Futures instrument statuses")?;
443
444 let instrument_map = instruments
445 .iter()
446 .map(|instrument| (instrument.id(), instrument.clone()))
447 .collect::<AHashMap<_, _>>();
448 let raw_to_id = instrument_map
449 .values()
450 .map(|instrument| (instrument.raw_symbol().inner(), instrument.id()))
451 .collect::<AHashMap<_, _>>();
452 let status_map = venue_statuses
453 .into_iter()
454 .filter_map(|(symbol, action)| {
455 raw_to_id
456 .get(&symbol)
457 .copied()
458 .map(|instrument_id| (instrument_id, action))
459 })
460 .collect::<AHashMap<_, _>>();
461
462 instruments_cache.store(instrument_map);
463 ws.replace_instruments(&instruments);
464 ws_public.replace_instruments(&instruments);
465
466 if emit_status_changes {
467 let mut cached_statuses = (**status_cache.load()).clone();
468 let ts = clock.get_time_ns();
469 diff_and_emit_statuses(&status_map, &mut cached_statuses, sender, ts, ts);
470 status_cache.store(cached_statuses);
471 } else {
472 status_cache.store(status_map);
473 }
474
475 for instrument in &instruments {
476 if let Err(e) = sender.send(DataEvent::Data(instrument.clone().into())) {
477 log::warn!("Failed to send refreshed Binance Futures instrument: {e}");
478 }
479 }
480
481 Ok(instruments)
482 }
483
484 fn custom_liquidation_instrument_id(
485 data_type: &DataType,
486 ) -> anyhow::Result<Option<InstrumentId>> {
487 let Some(raw_instrument_id) = data_type
488 .metadata()
489 .as_ref()
490 .and_then(|m| m.get("instrument_id"))
491 .and_then(|v| v.as_str())
492 .map(str::trim)
493 .filter(|value| !value.is_empty())
494 else {
495 return Ok(None);
496 };
497
498 let instrument_id = InstrumentId::from_str(raw_instrument_id)
499 .with_context(|| format!("invalid instrument_id metadata `{raw_instrument_id}`"))?;
500
501 Ok(Some(instrument_id))
502 }
503
504 fn required_instrument_id_metadata(data_type: &DataType) -> anyhow::Result<InstrumentId> {
505 let Some(raw_instrument_id) = data_type
506 .metadata()
507 .as_ref()
508 .and_then(|m| m.get("instrument_id"))
509 .and_then(|v| v.as_str())
510 .map(str::trim)
511 .filter(|value| !value.is_empty())
512 else {
513 anyhow::bail!("custom data request requires `instrument_id` metadata");
514 };
515
516 InstrumentId::from_str(raw_instrument_id)
517 .with_context(|| format!("invalid instrument_id metadata `{raw_instrument_id}`"))
518 }
519
520 fn required_period_metadata(data_type: &DataType) -> anyhow::Result<String> {
521 let Some(period) = data_type
522 .metadata()
523 .as_ref()
524 .and_then(|m| m.get("period"))
525 .and_then(|v| v.as_str())
526 .map(str::trim)
527 .filter(|value| !value.is_empty())
528 else {
529 anyhow::bail!("historical open interest request requires `period` metadata");
530 };
531
532 Ok(period.to_string())
533 }
534
535 fn coinm_open_interest_hist_params(
536 http: &BinanceFuturesHttpClient,
537 instrument_id: &InstrumentId,
538 ) -> anyhow::Result<(String, String)> {
539 let symbol = format_binance_symbol(instrument_id);
540 if let Some(pair) = symbol.strip_suffix("_PERP") {
541 return Ok((pair.to_string(), "PERPETUAL".to_string()));
542 }
543
544 let definition = http
545 .instrument_metadata(*instrument_id)
546 .with_context(|| format!("missing COIN-M definition for {instrument_id}"))?;
547 let BinanceFuturesInstrument::CoinM(definition) = definition else {
548 anyhow::bail!("expected a COIN-M definition for {instrument_id}");
549 };
550
551 Ok((definition.pair.to_string(), definition.contract_type))
552 }
553
554 fn parse_open_interest_decimal(field: &str, value: &str) -> anyhow::Result<Decimal> {
555 Decimal::from_str_exact(value)
556 .with_context(|| format!("invalid Binance open interest `{field}` value `{value}`"))
557 }
558
559 fn liquidation_data_type(instrument_id: InstrumentId) -> DataType {
560 let metadata = Params::new(
561 [(
562 "instrument_id".to_string(),
563 serde_json::Value::String(instrument_id.to_string()),
564 )]
565 .into(),
566 );
567 DataType::new(
568 "BinanceFuturesLiquidation",
569 Some(metadata),
570 Some(instrument_id.to_string()),
571 )
572 }
573
574 fn liquidation_stream(instrument_id: &InstrumentId) -> String {
575 format!("{}@forceOrder", format_binance_stream_symbol(instrument_id))
576 }
577
578 fn spawn_liquidation_stream_reconcile(&self, context: &'static str) {
579 let ws = self.ws_client.clone();
580 let refs = self.force_order_refs.clone();
581 let all_market_refs = self.force_order_all_market_refs.clone();
582 let all_market_stream_active = self.force_order_all_market_stream_active.clone();
583 let ws_lock = self.force_order_ws_lock.clone();
584
585 self.spawn_ws(
586 async move {
587 let _guard = ws_lock.lock().await;
588 let wants_all_market = all_market_refs.load(Ordering::Relaxed) > 0;
589 let all_market_active = all_market_stream_active.load(Ordering::Acquire);
590
591 if wants_all_market {
592 if all_market_active {
593 return Ok(());
594 }
595
596 let specific_streams = refs
597 .load()
598 .keys()
599 .map(Self::liquidation_stream)
600 .collect::<Vec<_>>();
601
602 if !specific_streams.is_empty() {
603 ws.unsubscribe(specific_streams).await.context(
604 "specific forceOrder unsubscribe while enabling all-market",
605 )?;
606 }
607
608 if all_market_refs.load(Ordering::Relaxed) == 0 {
609 let restored_streams = refs
610 .load()
611 .keys()
612 .map(Self::liquidation_stream)
613 .collect::<Vec<_>>();
614
615 if !restored_streams.is_empty() {
616 ws.subscribe(restored_streams).await.context(
617 "specific forceOrder restore after canceled all-market subscription",
618 )?;
619 }
620 all_market_stream_active.store(false, Ordering::Release);
621 return Ok(());
622 }
623
624 all_market_stream_active.store(true, Ordering::Release);
625
626 if let Err(e) = ws
627 .subscribe(vec!["!forceOrder@arr".to_string()])
628 .await
629 .context("all-market forceOrder subscription")
630 {
631 all_market_stream_active.store(false, Ordering::Release);
632 return Err(e);
633 }
634 } else {
635 if !all_market_active {
636 return Ok(());
637 }
638
639 ws.unsubscribe(vec!["!forceOrder@arr".to_string()])
640 .await
641 .context("all-market forceOrder unsubscribe")?;
642
643 let specific_streams = refs
644 .load()
645 .keys()
646 .map(Self::liquidation_stream)
647 .collect::<Vec<_>>();
648
649 if !specific_streams.is_empty() {
650 ws.subscribe(specific_streams).await.context(
651 "specific forceOrder resubscribe after all-market unsubscribe",
652 )?;
653 }
654 all_market_stream_active.store(false, Ordering::Release);
655 }
656
657 Ok(())
658 },
659 context,
660 );
661 }
662
663 #[expect(clippy::too_many_arguments)]
664 fn handle_ws_message(
665 msg: BinanceFuturesWsStreamsMessage,
666 data_sender: &EventSender<DataEvent>,
667 instruments: &Arc<AtomicMap<InstrumentId, InstrumentAny>>,
668 ws_instruments: &Arc<AtomicMap<Ustr, InstrumentAny>>,
669 book_sync: &BookSyncTracker,
670 book_subscriptions: &Arc<AtomicMap<InstrumentId, u32>>,
671 book_depths: &AtomicMap<InstrumentId, usize>,
672 book_unsubscribes_pending: &Arc<AtomicMap<InstrumentId, Vec<BookDrain>>>,
673 l1_book_subscriptions: &Arc<AtomicMap<InstrumentId, u32>>,
674 force_order_refs: &Arc<AtomicMap<InstrumentId, u32>>,
675 ticker_refs: &Arc<AtomicMap<InstrumentId, u32>>,
676 force_order_all_market_refs: &Arc<AtomicU32>,
677 force_order_all_market_stream_active: &Arc<AtomicBool>,
678 http_client: &BinanceFuturesHttpClient,
679 snapshot_timeout: Duration,
680 clock: &'static AtomicTime,
681 command_spawner: &TaskSpawner,
682 ) {
683 let ts_init = clock.get_time_ns();
684 let cache = ws_instruments.load();
685
686 match msg {
687 BinanceFuturesWsStreamsMessage::AggTrade(ref trade_msg) => {
688 if let Some(instrument) = cache.get(&trade_msg.symbol) {
689 match parse_agg_trade(trade_msg, instrument, ts_init) {
690 Ok(trade) => Self::send_data(data_sender, Data::Trade(trade)),
691 Err(e) => log::warn!("Failed to parse aggregate trade: {e}"),
692 }
693 }
694 }
695 BinanceFuturesWsStreamsMessage::Trade(ref trade_msg) => {
696 if let Some(instrument) = cache.get(&trade_msg.symbol) {
697 match parse_trade(trade_msg, instrument, ts_init) {
698 Ok(trade) => Self::send_data(data_sender, Data::Trade(trade)),
699 Err(e) => log::warn!("Failed to parse trade: {e}"),
700 }
701 }
702 }
703 BinanceFuturesWsStreamsMessage::BookTicker(ref ticker_msg) => {
704 if let Some(instrument) = cache.get(&ticker_msg.symbol) {
705 match parse_book_ticker(ticker_msg, instrument, ts_init) {
706 Ok(quote) => Self::send_top_of_book(
707 data_sender,
708 l1_book_subscriptions,
709 quote,
710 ticker_msg.update_id,
711 ),
712 Err(e) => log::warn!("Failed to parse book ticker: {e}"),
713 }
714 }
715 }
716 BinanceFuturesWsStreamsMessage::DepthUpdate(ref depth_msg) => {
717 if let Some(instrument) = cache.get(&depth_msg.symbol) {
718 let instrument_id = instrument.id();
719
720 let Some(depth) = book_subscriptions.load().get(&instrument_id).copied() else {
721 return;
722 };
723
724 if book_drain_active(book_unsubscribes_pending, instrument_id) {
729 log::debug!(
730 "Dropping depth frame for {instrument_id} with unsubscribe confirmation pending"
731 );
732 return;
733 }
734
735 if is_partial_book_depth(depth) {
736 match parse_depth_snapshot(depth_msg, instrument, ts_init) {
737 Ok(deltas) => {
738 send_book_snapshot(data_sender, book_depths, deltas);
739 }
740 Err(e) => log::warn!("Failed to parse depth update: {e}"),
741 }
742
743 return;
744 }
745
746 let deltas = if depth_msg.bids.is_empty() && depth_msg.asks.is_empty() {
749 None
750 } else {
751 match parse_depth_update(depth_msg, instrument, ts_init) {
752 Ok(deltas) => Some(deltas),
753 Err(e) => {
754 log::warn!("Failed to parse depth update: {e}");
755 return;
756 }
757 }
758 };
759
760 let update = DepthUpdate {
761 first_update_id: depth_msg.first_update_id,
762 final_update_id: depth_msg.final_update_id,
763 prev_final_update_id: Some(depth_msg.prev_final_update_id),
764 deltas,
765 };
766
767 if let Some(recovery) = book_sync.handle_update(instrument_id, update) {
768 let http = http_client.clone();
769 let instruments = instruments.clone();
770
771 spawn_recovery(
772 instrument_id,
773 recovery,
774 book_sync.clone(),
775 move |permit| {
776 Self::fetch_depth_snapshot(
777 http.clone(),
778 instruments.clone(),
779 instrument_id,
780 depth,
781 clock,
782 permit,
783 )
784 },
785 depth_request_weight(depth),
786 snapshot_timeout,
787 command_spawner,
788 );
789 }
790 }
791 }
792 BinanceFuturesWsStreamsMessage::MarkPrice(ref mark_msg) => {
793 if let Some(instrument) = cache.get(&mark_msg.symbol) {
794 match parse_mark_price(mark_msg, instrument, ts_init) {
795 Ok((mark_update, index_update, funding_update, custom_update)) => {
796 Self::send_data(data_sender, Data::MarkPrice(mark_update));
797 Self::send_data(data_sender, Data::IndexPrice(index_update));
798
799 if let Err(e) =
800 data_sender.send(DataEvent::Data(Data::FundingRate(funding_update)))
801 {
802 log::error!("Failed to emit funding rate: {e}");
803 }
804 let data_type = mark_price_data_type(instrument.id());
805 Self::send_data(
806 data_sender,
807 Data::Custom(CustomData::new(Arc::new(custom_update), data_type)),
808 );
809 }
810 Err(e) => log::warn!("Failed to parse mark price: {e}"),
811 }
812 }
813 }
814 BinanceFuturesWsStreamsMessage::Kline(ref kline_msg) => {
815 if let Some(instrument) = cache.get(&kline_msg.symbol) {
816 match parse_kline(kline_msg, instrument, ts_init) {
817 Ok(Some(bar)) => {
818 Self::send_data(data_sender, Data::Bar(bar.bar()));
819 let data_type = binance_bar_data_type(bar.bar_type);
820 Self::send_data(
821 data_sender,
822 Data::Custom(CustomData::new(Arc::new(bar), data_type)),
823 );
824 }
825 Ok(None) => {} Err(e) => log::warn!("Failed to parse kline: {e}"),
827 }
828 }
829 }
830 BinanceFuturesWsStreamsMessage::ForceOrder(ref liq_msg) => {
831 if let Some(instrument) = cache.get(&liq_msg.order.symbol) {
832 let ts_event = parse_millis_or_init(
833 liq_msg.event_time,
834 "Futures liquidation event time",
835 ts_init,
836 );
837 let parse_price = |value: &str, field: &str| -> anyhow::Result<Price> {
838 parse_required_price_at_precision(
839 value,
840 instrument.price_precision(),
841 field,
842 )
843 };
844
845 let parse_quantity = |value: &str, field: &str| -> anyhow::Result<Quantity> {
846 parse_required_quantity_at_precision(
847 value,
848 instrument.size_precision(),
849 field,
850 )
851 };
852
853 match (
854 parse_price(&liq_msg.order.price, "price"),
855 parse_price(&liq_msg.order.average_price, "average_price"),
856 parse_quantity(&liq_msg.order.last_filled_qty, "last_filled_qty"),
857 parse_quantity(&liq_msg.order.accumulated_qty, "accumulated_qty"),
858 ) {
859 (
860 Ok(price),
861 Ok(average_price),
862 Ok(last_filled_qty),
863 Ok(accumulated_qty),
864 ) => {
865 let liquidation = Arc::new(BinanceFuturesLiquidation::new(
866 instrument.id(),
867 OrderSide::from(liq_msg.order.side),
868 price,
869 average_price,
870 last_filled_qty,
871 accumulated_qty,
872 ts_event,
873 ts_init,
874 ));
875
876 let has_all_market_subscription =
877 force_order_all_market_refs.load(Ordering::Relaxed) > 0;
878 let has_all_market_stream =
879 force_order_all_market_stream_active.load(Ordering::Acquire);
880 let has_specific_subscription =
881 force_order_refs.load().contains_key(&instrument.id());
882
883 if has_all_market_subscription || has_all_market_stream {
884 let data_type =
885 DataType::new("BinanceFuturesLiquidation", None, None);
886 Self::send_data(
887 data_sender,
888 Data::Custom(CustomData::new(liquidation, data_type)),
889 );
890 } else if has_specific_subscription {
891 let data_type = Self::liquidation_data_type(instrument.id());
892 Self::send_data(
893 data_sender,
894 Data::Custom(CustomData::new(liquidation, data_type)),
895 );
896 }
897 }
898 (p, ap, lq, aq) => {
899 log::warn!(
900 "Failed to parse Binance liquidation {}: price={:?} avg={:?} \
901 last_qty={:?} accumulated_qty={:?}",
902 liq_msg.order.symbol,
903 p.err(),
904 ap.err(),
905 lq.err(),
906 aq.err(),
907 );
908 }
909 }
910 } else {
911 log::debug!(
912 "Received Binance liquidation for uncached symbol {}",
913 liq_msg.order.symbol
914 );
915 }
916 }
917 BinanceFuturesWsStreamsMessage::Ticker(ref ticker_msg) => {
918 if let Some(instrument) = cache.get(&ticker_msg.symbol) {
919 let instrument_id = instrument.id();
920 if !ticker_refs.load().contains_key(&instrument_id) {
921 return;
922 }
923
924 match parse_ticker(ticker_msg, instrument, ts_init) {
925 Ok(ticker) => {
926 let data_type = ticker_data_type(instrument_id);
927 Self::send_data(
928 data_sender,
929 Data::Custom(CustomData::new(Arc::new(ticker), data_type)),
930 );
931 }
932 Err(e) => log::warn!("Failed to parse ticker: {e}"),
933 }
934 }
935 }
936 BinanceFuturesWsStreamsMessage::AccountUpdate(_)
937 | BinanceFuturesWsStreamsMessage::OrderUpdate(_)
938 | BinanceFuturesWsStreamsMessage::TradeLite(_)
939 | BinanceFuturesWsStreamsMessage::AlgoUpdate(_)
940 | BinanceFuturesWsStreamsMessage::MarginCall(_)
941 | BinanceFuturesWsStreamsMessage::AccountConfigUpdate(_)
942 | BinanceFuturesWsStreamsMessage::ListenKeyExpired => {}
943 BinanceFuturesWsStreamsMessage::Error(e) => {
944 log::warn!(
945 "Binance Futures WebSocket error: code={}, msg={}",
946 e.code,
947 e.msg
948 );
949 }
950 BinanceFuturesWsStreamsMessage::Reconnected(abandoned) => {
951 log::info!("WebSocket reconnected, rebuilding order book snapshots");
952
953 for generation in abandoned {
956 remove_book_drain(book_unsubscribes_pending, generation);
957 }
958
959 book_sync.reset_on_reconnect();
960 }
961 BinanceFuturesWsStreamsMessage::Unsubscribed {
962 streams,
963 correlation,
964 } => {
965 log::debug!("Unsubscribe confirmed for streams {streams:?}");
966
967 if let Some(correlation) = correlation {
968 remove_book_drain(book_unsubscribes_pending, correlation);
969 }
970 }
971 }
972 }
973
974 fn send_top_of_book(
975 data_sender: &EventSender<DataEvent>,
976 l1_book_subscriptions: &Arc<AtomicMap<InstrumentId, u32>>,
977 quote: QuoteTick,
978 sequence: u64,
979 ) {
980 Self::send_data(data_sender, Data::Quote(quote));
981 if l1_book_subscriptions.contains_key("e.instrument_id) {
982 let deltas = quote_to_l1_deltas(quote, sequence);
983 Self::send_data(data_sender, Data::BookDeltas(Box::new(deltas)));
984 }
985 }
986
987 async fn fetch_depth_snapshot(
988 http: BinanceFuturesHttpClient,
989 instruments: Arc<AtomicMap<InstrumentId, InstrumentAny>>,
990 instrument_id: InstrumentId,
991 depth: u32,
992 clock: &'static AtomicTime,
993 permit: SnapshotPermit,
994 ) -> Result<DepthSnapshot, BinanceBookError> {
995 let symbol = format_binance_stream_symbol(&instrument_id).to_uppercase();
996 let params = BinanceDepthParams {
997 symbol,
998 limit: Some(depth),
999 };
1000
1001 let order_book = http
1002 .inner()
1003 .depth_paced(¶ms, permit)
1004 .await
1005 .map_err(|e| depth_snapshot_error(instrument_id, &e))?;
1006
1007 let ts_init = clock.get_time_ns();
1008
1009 let (price_precision, size_precision) = instruments
1010 .load()
1011 .get(&instrument_id)
1012 .map(|instrument| (instrument.price_precision(), instrument.size_precision()))
1013 .ok_or_else(|| {
1014 BinanceBookError::Permanent(format!("no instrument cached for {instrument_id}"))
1015 })?;
1016
1017 let deltas = parse_order_book_snapshot(
1018 &order_book,
1019 instrument_id,
1020 price_precision,
1021 size_precision,
1022 ts_init,
1023 );
1024
1025 Ok(DepthSnapshot {
1026 last_update_id: order_book.last_update_id as u64,
1027 deltas,
1028 has_event_time: true,
1029 })
1030 }
1031}
1032
1033fn upsert_instruments(
1034 cache: &Arc<AtomicMap<InstrumentId, InstrumentAny>>,
1035 instruments: &[InstrumentAny],
1036) {
1037 if instruments.is_empty() {
1038 return;
1039 }
1040
1041 cache.rcu(|cache| {
1042 for instrument in instruments {
1043 cache.insert(instrument.id(), instrument.clone());
1044 }
1045 });
1046}
1047
1048fn parse_order_book_snapshot(
1049 order_book: &BinanceOrderBook,
1050 instrument_id: InstrumentId,
1051 price_precision: u8,
1052 size_precision: u8,
1053 ts_init: UnixNanos,
1054) -> OrderBookDeltas {
1055 let sequence = order_book.last_update_id as u64;
1056 let ts_event = order_book.transaction_time.map_or(ts_init, |value| {
1057 parse_millis_or_init(
1058 value,
1059 "Futures order book snapshot transaction time",
1060 ts_init,
1061 )
1062 });
1063
1064 let total_levels = order_book.bids.len() + order_book.asks.len();
1065 let mut deltas = Vec::with_capacity(total_levels + 1);
1066
1067 deltas.push(OrderBookDelta::clear(
1068 instrument_id,
1069 sequence,
1070 ts_event,
1071 ts_init,
1072 ));
1073
1074 for (price_str, qty_str) in &order_book.bids {
1075 let Some(price) = parse_price_at_precision(price_str, price_precision) else {
1076 log::warn!(
1077 "Skipping Futures order book bid level for {instrument_id}: invalid or \
1078 non-positive price='{price_str}'"
1079 );
1080 continue;
1081 };
1082 let Some(size) = parse_quantity_at_precision(qty_str, size_precision) else {
1083 log::warn!(
1084 "Skipping Futures order book bid level for {instrument_id}: invalid or \
1085 non-positive quantity='{qty_str}'"
1086 );
1087 continue;
1088 };
1089
1090 let order = BookOrder::new(OrderSide::Buy, price, size, 0);
1091
1092 deltas.push(OrderBookDelta::new(
1093 instrument_id,
1094 BookAction::Add,
1095 order,
1096 RecordFlag::F_SNAPSHOT as u8,
1097 sequence,
1098 ts_event,
1099 ts_init,
1100 ));
1101 }
1102
1103 for (price_str, qty_str) in &order_book.asks {
1104 let Some(price) = parse_price_at_precision(price_str, price_precision) else {
1105 log::warn!(
1106 "Skipping Futures order book ask level for {instrument_id}: invalid or \
1107 non-positive price='{price_str}'"
1108 );
1109 continue;
1110 };
1111 let Some(size) = parse_quantity_at_precision(qty_str, size_precision) else {
1112 log::warn!(
1113 "Skipping Futures order book ask level for {instrument_id}: invalid or \
1114 non-positive quantity='{qty_str}'"
1115 );
1116 continue;
1117 };
1118
1119 let order = BookOrder::new(OrderSide::Sell, price, size, 0);
1120
1121 deltas.push(OrderBookDelta::new(
1122 instrument_id,
1123 BookAction::Add,
1124 order,
1125 RecordFlag::F_SNAPSHOT as u8,
1126 sequence,
1127 ts_event,
1128 ts_init,
1129 ));
1130 }
1131
1132 if let Some(delta) = deltas.last_mut() {
1133 delta.flags |= RecordFlag::F_LAST as u8;
1134 }
1135
1136 OrderBookDeltas::new(instrument_id, deltas)
1137}
1138
1139fn depth_snapshot_error(
1141 instrument_id: InstrumentId,
1142 e: &BinanceFuturesHttpError,
1143) -> BinanceBookError {
1144 let message = format!("depth snapshot request for {instrument_id} failed: {e}");
1145
1146 if e.is_retryable() || matches!(e, BinanceFuturesHttpError::RetryBudgetExceeded(_)) {
1147 BinanceBookError::Retryable(message)
1148 } else {
1149 BinanceBookError::Permanent(message)
1150 }
1151}
1152
1153#[async_trait::async_trait(?Send)]
1154impl DataClient for BinanceFuturesDataClient {
1155 fn client_id(&self) -> ClientId {
1156 self.client_id
1157 }
1158
1159 fn venue(&self) -> Option<Venue> {
1160 Some(self.venue())
1161 }
1162
1163 fn start(&mut self) -> anyhow::Result<()> {
1164 log::info!(
1165 "Started: client_id={}, product_type={:?}, environment={:?}",
1166 self.client_id,
1167 self.product_type,
1168 self.config.environment,
1169 );
1170 Ok(())
1171 }
1172
1173 fn stop(&mut self) -> anyhow::Result<()> {
1174 log::info!("Stopping {id}", id = self.client_id);
1175 self.session_tasks.begin_shutdown();
1176 self.command_tasks.begin_shutdown();
1177 self.ws_client.begin_shutdown();
1178 self.ws_public_client.begin_shutdown();
1179 self.is_connected.store(false, Ordering::Relaxed);
1180 Ok(())
1181 }
1182
1183 fn reset(&mut self) -> anyhow::Result<()> {
1184 log::debug!("Resetting {id}", id = self.client_id);
1185
1186 self.session_tasks.begin_shutdown();
1187 self.command_tasks.begin_shutdown();
1188 self.ws_client.begin_shutdown();
1189 self.ws_public_client.begin_shutdown();
1190 self.is_connected.store(false, Ordering::Relaxed);
1191
1192 self.mark_price_refs.store(AHashMap::new());
1194 self.ticker_refs.store(AHashMap::new());
1195 self.force_order_refs.store(AHashMap::new());
1196 self.force_order_all_market_refs.store(0, Ordering::Relaxed);
1197 self.force_order_all_market_stream_active
1198 .store(false, Ordering::Release);
1199 self.book_subscriptions.store(AHashMap::new());
1200 self.book_deltas.clear();
1201 self.book_depths.store(AHashMap::new());
1202 self.book_unsubscribes_pending.store(AHashMap::new());
1203 self.l1_book_subscriptions.store(AHashMap::new());
1204 self.quote_refs.store(AHashMap::new());
1205 self.book_sync.clear();
1206
1207 Ok(())
1208 }
1209
1210 fn dispose(&mut self) -> anyhow::Result<()> {
1211 log::debug!("Disposing {id}", id = self.client_id);
1212 self.stop()
1213 }
1214
1215 async fn connect(&mut self) -> anyhow::Result<()> {
1216 if self.is_connected() && self.session_tasks.is_open() && self.command_tasks.is_open() {
1217 return Ok(());
1218 }
1219
1220 register_binance_custom_data();
1221
1222 self.prepare_task_groups().await?;
1223 let ws_client = self.ws_client.clone();
1224 let ws_public_client = self.ws_public_client.clone();
1225 let setup_guard =
1226 TaskGroupGuard::new(&[&self.session_tasks, &self.command_tasks], move || {
1227 ws_client.begin_shutdown();
1228 ws_public_client.begin_shutdown();
1229 });
1230
1231 Self::refresh_instrument_catalog(
1232 &self.http_client,
1233 &self.config.instrument_provider,
1234 &self.instruments,
1235 &self.status_cache,
1236 &self.instrument_update_lock,
1237 &self.ws_client,
1238 &self.ws_public_client,
1239 &self.data_sender,
1240 self.clock,
1241 false,
1242 )
1243 .await?;
1244
1245 let session_result = async {
1246 log::info!("Connecting to Binance Futures market WebSocket...");
1247 self.ws_client.connect().await.map_err(|e| {
1248 anyhow::anyhow!("failed to connect Binance Futures market WebSocket: {e}")
1249 })?;
1250 log::info!("Binance Futures market WebSocket connected");
1251
1252 log::info!("Connecting to Binance Futures public WebSocket...");
1253 self.ws_public_client.connect().await.map_err(|e| {
1254 anyhow::anyhow!("failed to connect Binance Futures public WebSocket: {e}")
1255 })?;
1256 log::info!("Binance Futures public WebSocket connected");
1257
1258 let stream = self.ws_client.stream();
1259 let sender = self.data_sender.clone();
1260 let insts = self.instruments.clone();
1261 let ws_insts = self.ws_client.instruments_cache();
1262 let book_sync = self.book_sync.clone();
1263 let book_subs = self.book_subscriptions.clone();
1264 let book_depths = self.book_depths.clone();
1265 let book_unsubscribes_pending = self.book_unsubscribes_pending.clone();
1266 let l1_book_subs = self.l1_book_subscriptions.clone();
1267 let force_order_refs = self.force_order_refs.clone();
1268 let ticker_refs = self.ticker_refs.clone();
1269 let force_order_all_market_refs = self.force_order_all_market_refs.clone();
1270 let force_order_all_market_stream_active =
1271 self.force_order_all_market_stream_active.clone();
1272 let http = self.http_client.clone();
1273 let snapshot_timeout = Duration::from_secs(self.config.book_snapshot_timeout_secs);
1274 let clock = self.clock;
1275 let cancel = self.cancellation_token.clone();
1276 let command_spawner = self
1277 .command_tasks
1278 .spawner()
1279 .context("Binance Futures command task admission is closed")?;
1280
1281 let future = async move {
1282 pin_mut!(stream);
1283
1284 loop {
1285 tokio::select! {
1286 Some(message) = stream.next() => {
1287 Self::handle_ws_message(
1288 message,
1289 &sender,
1290 &insts,
1291 &ws_insts,
1292 &book_sync,
1293 &book_subs,
1294 &book_depths,
1295 &book_unsubscribes_pending,
1296 &l1_book_subs,
1297 &force_order_refs,
1298 &ticker_refs,
1299 &force_order_all_market_refs,
1300 &force_order_all_market_stream_active,
1301 &http,
1302 snapshot_timeout,
1303 clock,
1304 &command_spawner,
1305 );
1306 }
1307 () = cancel.cancelled() => {
1308 log::debug!("Market WebSocket stream task cancelled");
1309 break;
1310 }
1311 }
1312 }
1313 };
1314 self.session_tasks
1315 .spawn(future)
1316 .context("failed to register Binance Futures market stream task")?;
1317
1318 let pub_stream = self.ws_public_client.stream();
1319 let pub_sender = self.data_sender.clone();
1320 let pub_insts = self.instruments.clone();
1321 let pub_ws_insts = self.ws_public_client.instruments_cache();
1322 let pub_book_sync = self.book_sync.clone();
1323 let pub_book_subs = self.book_subscriptions.clone();
1324 let pub_book_depths = self.book_depths.clone();
1325 let pub_book_unsubscribes_pending = self.book_unsubscribes_pending.clone();
1326 let pub_l1_book_subs = self.l1_book_subscriptions.clone();
1327 let pub_force_order_refs = self.force_order_refs.clone();
1328 let pub_ticker_refs = self.ticker_refs.clone();
1329 let pub_force_order_all_market_refs = self.force_order_all_market_refs.clone();
1330 let pub_force_order_all_market_stream_active =
1331 self.force_order_all_market_stream_active.clone();
1332 let pub_http = self.http_client.clone();
1333 let pub_cancel = self.cancellation_token.clone();
1334 let pub_command_spawner = self
1335 .command_tasks
1336 .spawner()
1337 .context("Binance Futures command task admission is closed")?;
1338
1339 let future = async move {
1340 pin_mut!(pub_stream);
1341
1342 loop {
1343 tokio::select! {
1344 Some(message) = pub_stream.next() => {
1345 Self::handle_ws_message(
1346 message,
1347 &pub_sender,
1348 &pub_insts,
1349 &pub_ws_insts,
1350 &pub_book_sync,
1351 &pub_book_subs,
1352 &pub_book_depths,
1353 &pub_book_unsubscribes_pending,
1354 &pub_l1_book_subs,
1355 &pub_force_order_refs,
1356 &pub_ticker_refs,
1357 &pub_force_order_all_market_refs,
1358 &pub_force_order_all_market_stream_active,
1359 &pub_http,
1360 snapshot_timeout,
1361 clock,
1362 &pub_command_spawner,
1363 );
1364 }
1365 () = pub_cancel.cancelled() => {
1366 log::debug!("Public WebSocket stream task cancelled");
1367 break;
1368 }
1369 }
1370 }
1371 };
1372 self.session_tasks
1373 .spawn(future)
1374 .context("failed to register Binance Futures public stream task")?;
1375
1376 let poll_secs = self.config.instrument_status_poll_secs;
1377 if poll_secs > 0 {
1378 let poll_http = self.http_client.clone();
1379 let poll_sender = self.data_sender.clone();
1380 let poll_instruments = self.instruments.clone();
1381 let poll_status_cache = self.status_cache.clone();
1382 let poll_update_lock = self.instrument_update_lock.clone();
1383 let poll_cancel = self.cancellation_token.clone();
1384 let poll_clock = self.clock;
1385
1386 let future = async move {
1387 let mut interval =
1388 tokio::time::interval(tokio::time::Duration::from_secs(poll_secs));
1389 interval.tick().await; loop {
1392 tokio::select! {
1393 _ = interval.tick() => {
1394 let _guard = poll_update_lock.lock().await;
1395
1396 match poll_http.request_symbol_statuses().await {
1397 Ok(symbol_statuses) => {
1398 let ts = poll_clock.get_time_ns();
1399 let inst_guard = poll_instruments.load();
1400
1401 let raw_to_id: AHashMap<Ustr, InstrumentId> = inst_guard
1402 .values()
1403 .map(|inst| (inst.raw_symbol().inner(), inst.id()))
1404 .collect();
1405
1406 let mut new_statuses = AHashMap::new();
1407
1408 for (raw_symbol, action) in &symbol_statuses {
1409 if let Some(&id) = raw_to_id.get(raw_symbol) {
1410 new_statuses.insert(id, *action);
1411 }
1412 }
1413 drop(inst_guard);
1414
1415 let mut cache = (**poll_status_cache.load()).clone();
1416 diff_and_emit_statuses(
1417 &new_statuses, &mut cache, &poll_sender, ts, ts,
1418 );
1419 poll_status_cache.store(cache);
1420 }
1421 Err(e) => {
1422 log::warn!("Futures instrument status poll failed: {e}");
1423 }
1424 }
1425 }
1426 () = poll_cancel.cancelled() => {
1427 log::debug!("Futures instrument status polling task cancelled");
1428 break;
1429 }
1430 }
1431 }
1432 };
1433 self.session_tasks
1434 .spawn(future)
1435 .context("failed to register Binance Futures status polling task")?;
1436 log::debug!("Futures instrument status polling started: interval={poll_secs}s");
1437 }
1438
1439 let refresh_secs = self.config.instrument_refresh_interval_secs;
1440 if refresh_secs > 0 {
1441 let http = self.http_client.clone();
1442 let provider = self.config.instrument_provider.clone();
1443 let instruments = self.instruments.clone();
1444 let statuses = self.status_cache.clone();
1445 let update_lock = self.instrument_update_lock.clone();
1446 let ws = self.ws_client.clone();
1447 let ws_public = self.ws_public_client.clone();
1448 let sender = self.data_sender.clone();
1449 let clock = self.clock;
1450 let cancel = self.cancellation_token.clone();
1451
1452 let future = async move {
1453 let mut interval = tokio::time::interval(Duration::from_secs(refresh_secs));
1454 interval.tick().await;
1455
1456 loop {
1457 tokio::select! {
1458 _ = interval.tick() => {
1459 if let Err(e) = Self::refresh_instrument_catalog(
1460 &http,
1461 &provider,
1462 &instruments,
1463 &statuses,
1464 &update_lock,
1465 &ws,
1466 &ws_public,
1467 &sender,
1468 clock,
1469 true,
1470 ).await {
1471 log::warn!("Binance Futures instrument refresh failed: {e}");
1472 }
1473 }
1474 () = cancel.cancelled() => {
1475 log::debug!("Binance Futures instrument refresh task cancelled");
1476 break;
1477 }
1478 }
1479 }
1480 };
1481 self.session_tasks
1482 .spawn(future)
1483 .context("failed to register Binance Futures instrument refresh task")?;
1484 log::debug!("Futures instrument refresh started: interval={refresh_secs}s");
1485 }
1486
1487 Ok::<(), anyhow::Error>(())
1488 }
1489 .await;
1490
1491 if let Err(e) = session_result {
1492 if let Err(teardown_error) = self.teardown_partial_connect().await {
1493 return Err(e.context(format!(
1494 "Binance Futures data startup teardown failed: {teardown_error}"
1495 )));
1496 }
1497 return Err(e);
1498 }
1499
1500 setup_guard.disarm();
1501 self.is_connected.store(true, Ordering::Release);
1502 log::info!("Connected: client_id={}", self.client_id);
1503 Ok(())
1504 }
1505
1506 async fn disconnect(&mut self) -> anyhow::Result<()> {
1507 self.teardown_partial_connect().await?;
1508
1509 self.mark_price_refs.store(AHashMap::new());
1511 self.ticker_refs.store(AHashMap::new());
1512 self.force_order_refs.store(AHashMap::new());
1513 self.force_order_all_market_refs.store(0, Ordering::Relaxed);
1514 self.force_order_all_market_stream_active
1515 .store(false, Ordering::Release);
1516 self.book_subscriptions.store(AHashMap::new());
1517 self.book_deltas.clear();
1518 self.book_depths.store(AHashMap::new());
1519 self.book_unsubscribes_pending.store(AHashMap::new());
1520 self.l1_book_subscriptions.store(AHashMap::new());
1521 self.quote_refs.store(AHashMap::new());
1522 self.book_sync.clear();
1523
1524 self.is_connected.store(false, Ordering::Release);
1525 log::info!("Disconnected: client_id={}", self.client_id);
1526 Ok(())
1527 }
1528
1529 fn is_connected(&self) -> bool {
1530 self.is_connected.load(Ordering::Relaxed)
1531 }
1532
1533 fn is_disconnected(&self) -> bool {
1534 !self.is_connected()
1535 }
1536
1537 fn subscribe(&mut self, cmd: SubscribeCustomData) -> anyhow::Result<()> {
1538 let data_type = cmd.data_type.type_name();
1539 if data_type == "BinanceFuturesTicker" {
1540 return subscribe_ticker(self, &cmd.data_type);
1541 }
1542
1543 if data_type == "BinanceFuturesMarkPriceUpdate" {
1544 let instrument_id = Self::required_instrument_id_metadata(&cmd.data_type)?;
1545 anyhow::ensure!(
1546 instrument_id.venue == self.venue(),
1547 "Futures mark price requires a BINANCE instrument"
1548 );
1549 let should_subscribe = {
1550 let previous = self
1551 .mark_price_refs
1552 .load()
1553 .get(&instrument_id)
1554 .copied()
1555 .unwrap_or(0);
1556 self.mark_price_refs
1557 .rcu(|refs| *refs.entry(instrument_id).or_insert(0) += 1);
1558 previous == 0
1559 };
1560
1561 if should_subscribe {
1562 let ws = self.ws_client.clone();
1563 let stream = format!(
1564 "{}@markPrice@1s",
1565 format_binance_stream_symbol(&instrument_id)
1566 );
1567 self.spawn_ws(
1568 async move {
1569 ws.subscribe(vec![stream])
1570 .await
1571 .context("mark price custom subscription")
1572 },
1573 "mark price custom subscription",
1574 );
1575 }
1576 return Ok(());
1577 }
1578
1579 if data_type != "BinanceFuturesLiquidation" {
1580 log::warn!("Unsupported custom data subscription: {data_type}");
1581 return Ok(());
1582 }
1583
1584 let instrument_id = Self::custom_liquidation_instrument_id(&cmd.data_type)?;
1585 if let Some(instrument_id) = instrument_id {
1586 if instrument_id.venue != self.venue() {
1587 anyhow::bail!(
1588 "Binance liquidation custom data requires BINANCE venue instrument, received {instrument_id}"
1589 );
1590 }
1591
1592 let should_subscribe = {
1593 let prev = self
1594 .force_order_refs
1595 .load()
1596 .get(&instrument_id)
1597 .copied()
1598 .unwrap_or(0);
1599 self.force_order_refs.rcu(|m| {
1600 let count = m.entry(instrument_id).or_insert(0);
1601 *count += 1;
1602 });
1603 prev == 0
1604 };
1605
1606 let has_all_market_subscription =
1607 self.force_order_all_market_refs.load(Ordering::Relaxed) > 0;
1608 let has_all_market_stream = self
1609 .force_order_all_market_stream_active
1610 .load(Ordering::Acquire);
1611
1612 if should_subscribe && !has_all_market_subscription && !has_all_market_stream {
1613 let ws = self.ws_client.clone();
1614 let stream = Self::liquidation_stream(&instrument_id);
1615 self.spawn_ws(
1616 async move {
1617 ws.subscribe(vec![stream])
1618 .await
1619 .context("forceOrder subscription")
1620 },
1621 "forceOrder subscription",
1622 );
1623 } else if should_subscribe && !has_all_market_subscription {
1624 self.spawn_liquidation_stream_reconcile("forceOrder subscription restore");
1625 }
1626
1627 return Ok(());
1628 }
1629
1630 let should_subscribe = self
1631 .force_order_all_market_refs
1632 .fetch_add(1, Ordering::Relaxed)
1633 == 0;
1634
1635 if should_subscribe {
1636 self.spawn_liquidation_stream_reconcile("all-market forceOrder subscription");
1637 }
1638
1639 Ok(())
1640 }
1641
1642 fn subscribe_instruments(&mut self, _cmd: SubscribeInstruments) -> anyhow::Result<()> {
1643 log::debug!(
1644 "subscribe_instruments: Binance Futures instruments are fetched via HTTP on connect"
1645 );
1646 Ok(())
1647 }
1648
1649 fn subscribe_instrument(&mut self, _cmd: SubscribeInstrument) -> anyhow::Result<()> {
1650 log::debug!(
1651 "subscribe_instrument: Binance Futures instruments are fetched via HTTP on connect"
1652 );
1653 Ok(())
1654 }
1655
1656 fn subscribe_book_deltas(&mut self, cmd: SubscribeBookDeltas) -> anyhow::Result<()> {
1657 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1658 self.subscribe_book(&cmd.with_instrument_ids(instrument_id))?;
1659 self.book_deltas.insert(instrument_id);
1660 Ok(())
1661 })
1662 }
1663
1664 fn subscribe_book_depth(&mut self, cmd: SubscribeBookDepth) -> anyhow::Result<()> {
1665 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1666 anyhow::ensure!(
1667 cmd.book_type == BookType::L2_MBP,
1668 "Binance native depth snapshots require L2_MBP"
1669 );
1670 let depth = cmd.depth.map_or(DEPTH10_LEN, NonZeroUsize::get);
1671 anyhow::ensure!(
1672 depth <= BINANCE_PARTIAL_BOOK_DEPTH,
1673 "Binance native depth snapshots support at most {BINANCE_PARTIAL_BOOK_DEPTH} levels"
1674 );
1675
1676 let request = SubscribeBookDeltas::new(
1677 instrument_id,
1678 cmd.book_type,
1679 cmd.client_id,
1680 cmd.venue,
1681 cmd.command_id,
1682 cmd.ts_init,
1683 NonZeroUsize::new(BINANCE_PARTIAL_BOOK_DEPTH),
1684 cmd.managed,
1685 cmd.correlation_id,
1686 cmd.params.clone(),
1687 );
1688
1689 if let Some(active) = self.book_depths.get_cloned(&instrument_id) {
1690 anyhow::ensure!(
1691 active == depth,
1692 "Binance snapshot depth cannot change while subscribed"
1693 );
1694
1695 return self.subscribe_book(&request);
1696 }
1697
1698 self.book_depths.insert(instrument_id, depth);
1699 if let Err(e) = self.subscribe_book(&request) {
1700 self.book_depths.remove(&instrument_id);
1701 return Err(e);
1702 }
1703
1704 Ok(())
1705 })
1706 }
1707
1708 fn subscribe_quotes(&mut self, cmd: SubscribeQuotes) -> anyhow::Result<()> {
1709 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1710 self.subscribe_top_of_book(instrument_id);
1711 Ok(())
1712 })
1713 }
1714
1715 fn subscribe_trades(&mut self, cmd: SubscribeTrades) -> anyhow::Result<()> {
1716 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1717 let ws = self.ws_client.clone();
1718
1719 let stream = format!("{}@aggTrade", format_binance_stream_symbol(&instrument_id));
1721
1722 self.spawn_ws(
1723 async move {
1724 ws.subscribe(vec![stream])
1725 .await
1726 .context("trades subscription")
1727 },
1728 "trade subscription",
1729 );
1730
1731 Ok(())
1732 })
1733 }
1734
1735 fn subscribe_bars(&mut self, cmd: SubscribeBars) -> anyhow::Result<()> {
1736 execute_bar_subscriptions(&cmd.bar_types, |bar_type| {
1737 let ws = self.ws_client.clone();
1738 let interval = bar_spec_to_binance_interval(bar_type.spec())?;
1739 anyhow::ensure!(
1740 interval != crate::common::enums::BinanceKlineInterval::Second1,
1741 "Binance Futures does not support second-level kline intervals"
1742 );
1743
1744 let stream = format!(
1745 "{}@kline_{}",
1746 format_binance_stream_symbol(&bar_type.instrument_id()),
1747 interval.as_str()
1748 );
1749
1750 self.spawn_ws(
1751 async move {
1752 ws.subscribe(vec![stream])
1753 .await
1754 .context("bars subscription")
1755 },
1756 "bar subscription",
1757 );
1758
1759 Ok(())
1760 })
1761 }
1762
1763 fn subscribe_mark_prices(&mut self, cmd: SubscribeMarkPrices) -> anyhow::Result<()> {
1764 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1765 let should_subscribe = {
1766 let prev = self
1767 .mark_price_refs
1768 .load()
1769 .get(&instrument_id)
1770 .copied()
1771 .unwrap_or(0);
1772 self.mark_price_refs.rcu(|m| {
1773 let count = m.entry(instrument_id).or_insert(0);
1774 *count += 1;
1775 });
1776
1777 prev == 0
1778 };
1779
1780 if should_subscribe {
1781 let ws = self.ws_client.clone();
1782 let stream = format!(
1783 "{}@markPrice@1s",
1784 format_binance_stream_symbol(&instrument_id)
1785 );
1786
1787 self.spawn_ws(
1788 async move {
1789 ws.subscribe(vec![stream])
1790 .await
1791 .context("mark prices subscription")
1792 },
1793 "mark prices subscription",
1794 );
1795 }
1796
1797 Ok(())
1798 })
1799 }
1800
1801 fn subscribe_index_prices(&mut self, cmd: SubscribeIndexPrices) -> anyhow::Result<()> {
1802 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1803 let should_subscribe = {
1804 let prev = self
1805 .mark_price_refs
1806 .load()
1807 .get(&instrument_id)
1808 .copied()
1809 .unwrap_or(0);
1810 self.mark_price_refs.rcu(|m| {
1811 let count = m.entry(instrument_id).or_insert(0);
1812 *count += 1;
1813 });
1814
1815 prev == 0
1816 };
1817
1818 if should_subscribe {
1819 let ws = self.ws_client.clone();
1820 let stream = format!(
1821 "{}@markPrice@1s",
1822 format_binance_stream_symbol(&instrument_id)
1823 );
1824
1825 self.spawn_ws(
1826 async move {
1827 ws.subscribe(vec![stream])
1828 .await
1829 .context("index prices subscription")
1830 },
1831 "index prices subscription",
1832 );
1833 }
1834
1835 Ok(())
1836 })
1837 }
1838
1839 fn subscribe_funding_rates(&mut self, cmd: SubscribeFundingRates) -> anyhow::Result<()> {
1840 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1841 let should_subscribe = {
1842 let prev = self
1843 .mark_price_refs
1844 .load()
1845 .get(&instrument_id)
1846 .copied()
1847 .unwrap_or(0);
1848 self.mark_price_refs.rcu(|m| {
1849 let count = m.entry(instrument_id).or_insert(0);
1850 *count += 1;
1851 });
1852
1853 prev == 0
1854 };
1855
1856 if should_subscribe {
1857 let ws = self.ws_client.clone();
1858 let stream = format!(
1859 "{}@markPrice@1s",
1860 format_binance_stream_symbol(&instrument_id)
1861 );
1862
1863 self.spawn_ws(
1864 async move {
1865 ws.subscribe(vec![stream])
1866 .await
1867 .context("funding rates subscription")
1868 },
1869 "funding rates subscription",
1870 );
1871 }
1872
1873 Ok(())
1874 })
1875 }
1876
1877 fn subscribe_instrument_status(
1878 &mut self,
1879 cmd: SubscribeInstrumentStatus,
1880 ) -> anyhow::Result<()> {
1881 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1882 log::debug!(
1883 "subscribe_instrument_status: {instrument_id} (status changes detected via periodic exchange info polling)",
1884 );
1885 Ok(())
1886 })
1887 }
1888
1889 fn unsubscribe_book_deltas(&mut self, cmd: &UnsubscribeBookDeltas) -> anyhow::Result<()> {
1890 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1891 self.book_deltas.remove(&instrument_id);
1892 if !self.book_depths.contains_key(&instrument_id) {
1893 self.unsubscribe_book(&cmd.with_instrument_ids(instrument_id))?;
1894 }
1895
1896 Ok(())
1897 })
1898 }
1899
1900 fn unsubscribe_book_depth(&mut self, cmd: &UnsubscribeBookDepth) -> anyhow::Result<()> {
1901 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1902 self.book_depths.remove(&instrument_id);
1903 if !self.book_deltas.contains(&instrument_id) {
1904 let request = UnsubscribeBookDeltas::new(
1905 instrument_id,
1906 cmd.client_id,
1907 cmd.venue,
1908 cmd.command_id,
1909 cmd.ts_init,
1910 cmd.correlation_id,
1911 cmd.params.clone(),
1912 );
1913 self.unsubscribe_book(&request)?;
1914 }
1915
1916 Ok(())
1917 })
1918 }
1919
1920 fn unsubscribe_quotes(&mut self, cmd: &UnsubscribeQuotes) -> anyhow::Result<()> {
1921 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1922 self.unsubscribe_top_of_book(instrument_id);
1923 Ok(())
1924 })
1925 }
1926
1927 fn unsubscribe_trades(&mut self, cmd: &UnsubscribeTrades) -> anyhow::Result<()> {
1928 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1929 let ws = self.ws_client.clone();
1930
1931 let stream = format!("{}@aggTrade", format_binance_stream_symbol(&instrument_id));
1932
1933 self.spawn_ws(
1934 async move {
1935 ws.unsubscribe(vec![stream])
1936 .await
1937 .context("trades unsubscribe")
1938 .map(|_| ())
1939 },
1940 "trade unsubscribe",
1941 );
1942
1943 Ok(())
1944 })
1945 }
1946
1947 fn unsubscribe(&mut self, cmd: &UnsubscribeCustomData) -> anyhow::Result<()> {
1948 let data_type = cmd.data_type.type_name();
1949 if data_type == "BinanceFuturesTicker" {
1950 return unsubscribe_ticker(self, &cmd.data_type);
1951 }
1952
1953 if data_type == "BinanceFuturesMarkPriceUpdate" {
1954 let instrument_id = Self::required_instrument_id_metadata(&cmd.data_type)?;
1955 let should_unsubscribe = match self.mark_price_refs.load().get(&instrument_id).copied()
1956 {
1957 Some(1) => {
1958 self.mark_price_refs.remove(&instrument_id);
1959 true
1960 }
1961 Some(count) if count > 1 => {
1962 self.mark_price_refs.rcu(|refs| {
1963 if let Some(existing) = refs.get_mut(&instrument_id) {
1964 *existing -= 1;
1965 }
1966 });
1967 false
1968 }
1969 _ => false,
1970 };
1971
1972 if should_unsubscribe {
1973 let ws = self.ws_client.clone();
1974 let stream = format!(
1975 "{}@markPrice@1s",
1976 format_binance_stream_symbol(&instrument_id)
1977 );
1978 self.spawn_ws(
1979 async move {
1980 ws.unsubscribe(vec![stream])
1981 .await
1982 .context("mark price custom unsubscribe")
1983 .map(|_| ())
1984 },
1985 "mark price custom unsubscribe",
1986 );
1987 }
1988 return Ok(());
1989 }
1990
1991 if data_type != "BinanceFuturesLiquidation" {
1992 log::warn!("Unsupported custom data unsubscription: {data_type}");
1993 return Ok(());
1994 }
1995
1996 let instrument_id = Self::custom_liquidation_instrument_id(&cmd.data_type)?;
1997 if let Some(instrument_id) = instrument_id {
1998 if instrument_id.venue != self.venue() {
1999 anyhow::bail!(
2000 "Binance liquidation custom data requires BINANCE venue instrument, received {instrument_id}"
2001 );
2002 }
2003
2004 let should_unsubscribe = {
2005 let prev = self.force_order_refs.load().get(&instrument_id).copied();
2006 match prev {
2007 Some(1) => {
2008 self.force_order_refs.remove(&instrument_id);
2009 true
2010 }
2011 Some(count) if count > 1 => {
2012 self.force_order_refs.rcu(|m| {
2013 if let Some(existing) = m.get_mut(&instrument_id) {
2014 *existing -= 1;
2015 }
2016 });
2017 false
2018 }
2019 _ => false,
2020 }
2021 };
2022
2023 let has_all_market_subscription =
2024 self.force_order_all_market_refs.load(Ordering::Relaxed) > 0;
2025 let has_all_market_stream = self
2026 .force_order_all_market_stream_active
2027 .load(Ordering::Acquire);
2028
2029 if should_unsubscribe && !has_all_market_subscription {
2030 let ws = self.ws_client.clone();
2031 let stream = Self::liquidation_stream(&instrument_id);
2032 let ws_lock = self.force_order_ws_lock.clone();
2033 self.spawn_ws(
2034 async move {
2035 let _guard = if has_all_market_stream {
2036 Some(ws_lock.lock().await)
2037 } else {
2038 None
2039 };
2040 ws.unsubscribe(vec![stream])
2041 .await
2042 .context("forceOrder unsubscribe")
2043 .map(|_| ())
2044 },
2045 "forceOrder unsubscribe",
2046 );
2047 }
2048
2049 return Ok(());
2050 }
2051
2052 let should_unsubscribe = self
2053 .force_order_all_market_refs
2054 .try_update(Ordering::Relaxed, Ordering::Relaxed, |current| {
2055 if current == 0 {
2056 None
2057 } else {
2058 Some(current - 1)
2059 }
2060 })
2061 .is_ok_and(|prev| prev == 1);
2062
2063 if should_unsubscribe {
2064 self.spawn_liquidation_stream_reconcile("all-market forceOrder unsubscribe");
2065 }
2066
2067 Ok(())
2068 }
2069
2070 fn unsubscribe_bars(&mut self, cmd: &UnsubscribeBars) -> anyhow::Result<()> {
2071 execute_bar_subscriptions(&cmd.bar_types, |bar_type| {
2072 let ws = self.ws_client.clone();
2073 let interval = bar_spec_to_binance_interval(bar_type.spec())?;
2074
2075 let stream = format!(
2076 "{}@kline_{}",
2077 format_binance_stream_symbol(&bar_type.instrument_id()),
2078 interval.as_str()
2079 );
2080
2081 self.spawn_ws(
2082 async move {
2083 ws.unsubscribe(vec![stream])
2084 .await
2085 .context("bars unsubscribe")
2086 .map(|_| ())
2087 },
2088 "bar unsubscribe",
2089 );
2090
2091 Ok(())
2092 })
2093 }
2094
2095 fn unsubscribe_mark_prices(&mut self, cmd: &UnsubscribeMarkPrices) -> anyhow::Result<()> {
2096 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2097 let should_unsubscribe = {
2098 let prev = self.mark_price_refs.load().get(&instrument_id).copied();
2099 match prev {
2100 Some(count) if count <= 1 => {
2101 self.mark_price_refs.remove(&instrument_id);
2102 true
2103 }
2104 Some(_) => {
2105 self.mark_price_refs.rcu(|m| {
2106 if let Some(count) = m.get_mut(&instrument_id) {
2107 *count = count.saturating_sub(1);
2108 }
2109 });
2110
2111 false
2112 }
2113 None => false,
2114 }
2115 };
2116
2117 if should_unsubscribe {
2118 let ws = self.ws_client.clone();
2119 let symbol_lower = format_binance_stream_symbol(&instrument_id);
2120 let streams = vec![
2121 format!("{symbol_lower}@markPrice"),
2122 format!("{symbol_lower}@markPrice@1s"),
2123 format!("{symbol_lower}@markPrice@3s"),
2124 ];
2125
2126 self.spawn_ws(
2127 async move {
2128 ws.unsubscribe(streams)
2129 .await
2130 .context("mark prices unsubscribe")
2131 .map(|_| ())
2132 },
2133 "mark prices unsubscribe",
2134 );
2135 }
2136
2137 Ok(())
2138 })
2139 }
2140
2141 fn unsubscribe_index_prices(&mut self, cmd: &UnsubscribeIndexPrices) -> anyhow::Result<()> {
2142 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2143 let should_unsubscribe = {
2144 let prev = self.mark_price_refs.load().get(&instrument_id).copied();
2145 match prev {
2146 Some(count) if count <= 1 => {
2147 self.mark_price_refs.remove(&instrument_id);
2148 true
2149 }
2150 Some(_) => {
2151 self.mark_price_refs.rcu(|m| {
2152 if let Some(count) = m.get_mut(&instrument_id) {
2153 *count = count.saturating_sub(1);
2154 }
2155 });
2156
2157 false
2158 }
2159 None => false,
2160 }
2161 };
2162
2163 if should_unsubscribe {
2164 let ws = self.ws_client.clone();
2165 let symbol_lower = format_binance_stream_symbol(&instrument_id);
2166 let streams = vec![
2167 format!("{symbol_lower}@markPrice"),
2168 format!("{symbol_lower}@markPrice@1s"),
2169 format!("{symbol_lower}@markPrice@3s"),
2170 ];
2171
2172 self.spawn_ws(
2173 async move {
2174 ws.unsubscribe(streams)
2175 .await
2176 .context("index prices unsubscribe")
2177 .map(|_| ())
2178 },
2179 "index prices unsubscribe",
2180 );
2181 }
2182
2183 Ok(())
2184 })
2185 }
2186
2187 fn unsubscribe_funding_rates(&mut self, cmd: &UnsubscribeFundingRates) -> anyhow::Result<()> {
2188 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2189 let should_unsubscribe = {
2190 let prev = self.mark_price_refs.load().get(&instrument_id).copied();
2191 match prev {
2192 Some(count) if count <= 1 => {
2193 self.mark_price_refs.remove(&instrument_id);
2194 true
2195 }
2196 Some(_) => {
2197 self.mark_price_refs.rcu(|m| {
2198 if let Some(count) = m.get_mut(&instrument_id) {
2199 *count = count.saturating_sub(1);
2200 }
2201 });
2202
2203 false
2204 }
2205 None => false,
2206 }
2207 };
2208
2209 if should_unsubscribe {
2210 let ws = self.ws_client.clone();
2211 let symbol_lower = format_binance_stream_symbol(&instrument_id);
2212 let streams = vec![
2213 format!("{symbol_lower}@markPrice"),
2214 format!("{symbol_lower}@markPrice@1s"),
2215 format!("{symbol_lower}@markPrice@3s"),
2216 ];
2217
2218 self.spawn_ws(
2219 async move {
2220 ws.unsubscribe(streams)
2221 .await
2222 .context("funding rates unsubscribe")
2223 .map(|_| ())
2224 },
2225 "funding rates unsubscribe",
2226 );
2227 }
2228
2229 Ok(())
2230 })
2231 }
2232
2233 fn unsubscribe_instrument_status(
2234 &mut self,
2235 cmd: &UnsubscribeInstrumentStatus,
2236 ) -> anyhow::Result<()> {
2237 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2238 log::debug!("unsubscribe_instrument_status: {instrument_id}",);
2239 Ok(())
2240 })
2241 }
2242
2243 fn request_instruments(&self, request: RequestInstruments) -> anyhow::Result<()> {
2244 let http = self.http_client.clone();
2245 let sender = self.data_sender.clone();
2246 let instruments_cache = self.instruments.clone();
2247 let request_id = request.request_id;
2248 let client_id = request.client_id.unwrap_or(self.client_id);
2249 let venue = self.venue();
2250 let start = request.start;
2251 let end = request.end;
2252 let params = request.params;
2253 let clock = self.clock;
2254 let provider = self.config.instrument_provider.clone();
2255 let start_nanos = datetime_to_unix_nanos(start);
2256 let end_nanos = datetime_to_unix_nanos(end);
2257
2258 self.spawn_command(async move {
2259 match http.request_instruments_with_config(&provider).await {
2260 Ok(instruments) => {
2261 upsert_instruments(&instruments_cache, &instruments);
2262
2263 let response = DataResponse::Instruments(InstrumentsResponse::new(
2264 request_id,
2265 client_id,
2266 venue,
2267 instruments,
2268 start_nanos,
2269 end_nanos,
2270 clock.get_time_ns(),
2271 params,
2272 ));
2273
2274 if let Err(e) = sender.send(DataEvent::Response(response)) {
2275 log::error!("Failed to send instruments response: {e}");
2276 }
2277 }
2278 Err(e) => log::error!("Instruments request failed: {e:?}"),
2279 }
2280 });
2281
2282 Ok(())
2283 }
2284
2285 fn request_instrument(&self, request: RequestInstrument) -> anyhow::Result<()> {
2286 let http = self.http_client.clone();
2287 let sender = self.data_sender.clone();
2288 let instruments = self.instruments.clone();
2289 let instrument_id = request.single_instrument_id()?;
2290 let request_id = request.request_id;
2291 let client_id = request.client_id.unwrap_or(self.client_id);
2292 let start = request.start;
2293 let end = request.end;
2294 let params = request.params;
2295 let clock = self.clock;
2296 let provider = self.config.instrument_provider.clone();
2297 let start_nanos = datetime_to_unix_nanos(start);
2298 let end_nanos = datetime_to_unix_nanos(end);
2299
2300 self.spawn_command(async move {
2301 match http.request_instruments_with_config(&provider).await {
2302 Ok(all_instruments) => {
2303 upsert_instruments(&instruments, &all_instruments);
2304
2305 let instrument = all_instruments
2306 .into_iter()
2307 .find(|i| i.id() == instrument_id);
2308
2309 if let Some(instrument) = instrument {
2310 let response = DataResponse::Instrument(Box::new(InstrumentResponse::new(
2311 request_id,
2312 client_id,
2313 instrument.id(),
2314 instrument,
2315 start_nanos,
2316 end_nanos,
2317 clock.get_time_ns(),
2318 params,
2319 )));
2320
2321 if let Err(e) = sender.send(DataEvent::Response(response)) {
2322 log::error!("Failed to send instrument response: {e}");
2323 }
2324 } else {
2325 log::error!("Instrument not found: {instrument_id}");
2326 }
2327 }
2328 Err(e) => log::error!("Instrument request failed: {e:?}"),
2329 }
2330 });
2331
2332 Ok(())
2333 }
2334
2335 fn request_data(&self, request: RequestCustomData) -> anyhow::Result<()> {
2340 let data_type = request.data_type.clone();
2341 let data_type_name = data_type.type_name().to_string();
2342
2343 if data_type_name == "BinanceBar" {
2344 let bar_type = parse_binance_bar_type(&data_type)?;
2345 anyhow::ensure!(
2346 bar_type.aggregation_source() == AggregationSource::External,
2347 "historical BinanceBar requests require EXTERNAL aggregation"
2348 );
2349 anyhow::ensure!(
2350 bar_type.spec().price_type == PriceType::Last,
2351 "historical BinanceBar requests require LAST price type"
2352 );
2353 anyhow::ensure!(
2354 bar_type.spec().is_time_aggregated(),
2355 "historical BinanceBar requests require time aggregation"
2356 );
2357 let http = self.http_client.clone();
2358 let sender = self.data_sender.clone();
2359 let request_id = request.request_id;
2360 let client_id = request.client_id;
2361 let start = request.start;
2362 let end = request.end;
2363 let limit = request.limit.map(|value| value.get() as u32);
2364 let params = request.params;
2365 let clock = self.clock;
2366 let venue = self.venue();
2367 let start_nanos = datetime_to_unix_nanos(start);
2368 let end_nanos = datetime_to_unix_nanos(end);
2369 self.spawn_command(async move {
2370 match http.request_binance_bars(bar_type, start, end, limit).await {
2371 Ok(bars) => {
2372 let response = DataResponse::Data(CustomDataResponse::new(
2373 request_id,
2374 client_id,
2375 Some(venue),
2376 data_type,
2377 binance_bars_to_custom_data(bar_type, bars),
2378 start_nanos,
2379 end_nanos,
2380 clock.get_time_ns(),
2381 params,
2382 ));
2383
2384 if let Err(e) = sender.send(DataEvent::Response(response)) {
2385 log::error!("Failed to send BinanceBar response: {e}");
2386 }
2387 }
2388 Err(e) => log::error!("BinanceBar request failed for {bar_type}: {e:?}"),
2389 }
2390 });
2391 return Ok(());
2392 }
2393
2394 if data_type_name != "BinanceFuturesOpenInterest"
2395 && data_type_name != "BinanceFuturesOpenInterestHist"
2396 {
2397 log::warn!("Unsupported custom data request: {data_type_name}");
2398 return Ok(());
2399 }
2400
2401 let instrument_id = Self::required_instrument_id_metadata(&data_type)?;
2402
2403 if instrument_id.venue != self.venue() {
2404 anyhow::bail!(
2405 "Binance Futures custom data requires BINANCE venue instrument, received {instrument_id}"
2406 );
2407 }
2408
2409 let period = if data_type_name == "BinanceFuturesOpenInterestHist" {
2410 Some(Self::required_period_metadata(&data_type)?)
2411 } else {
2412 None
2413 };
2414
2415 let http = self.http_client.clone();
2416 let sender = self.data_sender.clone();
2417 let request_id = request.request_id;
2418 let client_id = request.client_id;
2419 let params = request.params;
2420 let clock = self.clock;
2421 let venue = self.venue();
2422 let limit = request.limit.map(|n| n.get() as u32);
2423 let start_nanos = datetime_to_unix_nanos(request.start);
2424 let end_nanos = datetime_to_unix_nanos(request.end);
2425 let start_ms = request.start.map(|dt| dt.as_millisecond());
2426 let end_ms = request.end.map(|dt| dt.as_millisecond());
2427
2428 self.spawn_command(async move {
2429 let response = if data_type_name == "BinanceFuturesOpenInterest" {
2430 let response_data_type = data_type.clone();
2431 let query = BinanceOpenInterestParams {
2432 symbol: format_binance_symbol(&instrument_id),
2433 };
2434
2435 match http
2436 .open_interest(&query)
2437 .await
2438 .context("failed to request current open interest from Binance Futures")
2439 {
2440 Ok(open_interest) => {
2441 let ts_init = clock.get_time_ns();
2442 let open_interest_value = match Self::parse_open_interest_decimal(
2443 "open_interest",
2444 &open_interest.open_interest,
2445 ) {
2446 Ok(value) => value,
2447 Err(e) => {
2448 log::error!(
2449 "Current open interest request failed for {instrument_id}: {e:?}"
2450 );
2451 return;
2452 }
2453 };
2454 let ts_event = match parse_millis(
2455 open_interest.time,
2456 "Futures open interest time",
2457 ) {
2458 Ok(value) => value,
2459 Err(e) => {
2460 log::error!(
2461 "Current open interest request failed for {instrument_id}: {e:?}"
2462 );
2463 return;
2464 }
2465 };
2466 let payload = Arc::new(BinanceFuturesOpenInterest::new(
2467 instrument_id,
2468 open_interest_value,
2469 ts_event,
2470 ts_init,
2471 ));
2472 let custom = CustomData::new(payload, response_data_type.clone());
2473
2474 Some(DataResponse::Data(CustomDataResponse::new(
2475 request_id,
2476 client_id,
2477 Some(venue),
2478 response_data_type,
2479 custom,
2480 start_nanos,
2481 end_nanos,
2482 ts_init,
2483 params,
2484 )))
2485 }
2486 Err(e) => {
2487 log::error!("Current open interest request failed for {instrument_id}: {e:?}");
2488 None
2489 }
2490 }
2491 } else {
2492 let response_data_type = data_type.clone();
2493 let period = period.expect("period required for historical open interest");
2494 let query = match http.product_type() {
2495 BinanceProductType::UsdM => BinanceOpenInterestHistParams {
2496 symbol: Some(format_binance_symbol(&instrument_id)),
2497 pair: None,
2498 contract_type: None,
2499 period: period.clone(),
2500 start_time: start_ms,
2501 end_time: end_ms,
2502 limit,
2503 },
2504 BinanceProductType::CoinM => {
2505 let (pair, contract_type) =
2506 match Self::coinm_open_interest_hist_params(&http, &instrument_id) {
2507 Ok(values) => values,
2508 Err(e) => {
2509 log::error!(
2510 "Historical open interest request failed for {instrument_id}: {e:?}"
2511 );
2512 return;
2513 }
2514 };
2515 BinanceOpenInterestHistParams {
2516 symbol: None,
2517 pair: Some(pair),
2518 contract_type: Some(contract_type),
2519 period: period.clone(),
2520 start_time: start_ms,
2521 end_time: end_ms,
2522 limit,
2523 }
2524 }
2525 product_type => {
2526 log::error!(
2527 "Historical open interest request failed for {instrument_id}: unsupported product type {product_type:?}"
2528 );
2529 return;
2530 }
2531 };
2532
2533 match http
2534 .open_interest_hist(&query)
2535 .await
2536 .context("failed to request historical open interest from Binance Futures")
2537 {
2538 Ok(history) => {
2539 let ts_init = clock.get_time_ns();
2540 let points: Vec<BinanceFuturesOpenInterestHistPoint> = match history
2541 .into_iter()
2542 .map(|point| -> anyhow::Result<_> {
2543 Ok(BinanceFuturesOpenInterestHistPoint::new(
2544 Self::parse_open_interest_decimal(
2545 "sum_open_interest",
2546 &point.sum_open_interest,
2547 )?,
2548 Self::parse_open_interest_decimal(
2549 "sum_open_interest_value",
2550 &point.sum_open_interest_value,
2551 )?,
2552 parse_millis(
2553 point.timestamp,
2554 "Futures historical open interest timestamp",
2555 )?,
2556 ))
2557 })
2558 .collect()
2559 {
2560 Ok(points) => points,
2561 Err(e) => {
2562 log::error!(
2563 "Historical open interest request failed for {instrument_id}: {e:?}"
2564 );
2565 return;
2566 }
2567 };
2568 let ts_event = points.last().map_or(ts_init, |point| point.ts_event);
2569 let payload = Arc::new(BinanceFuturesOpenInterestHist::new(
2570 instrument_id,
2571 period,
2572 points,
2573 ts_event,
2574 ts_init,
2575 ));
2576 let custom = CustomData::new(payload, response_data_type.clone());
2577
2578 Some(DataResponse::Data(CustomDataResponse::new(
2579 request_id,
2580 client_id,
2581 Some(venue),
2582 response_data_type,
2583 custom,
2584 start_nanos,
2585 end_nanos,
2586 ts_init,
2587 params,
2588 )))
2589 }
2590 Err(e) => {
2591 log::error!(
2592 "Historical open interest request failed for {instrument_id}: {e:?}"
2593 );
2594 None
2595 }
2596 }
2597 };
2598
2599 if let Some(response) = response
2600 && let Err(e) = sender.send(DataEvent::Response(response))
2601 {
2602 log::error!("Failed to send custom data response: {e}");
2603 }
2604 });
2605
2606 Ok(())
2607 }
2608
2609 fn request_trades(&self, request: RequestTrades) -> anyhow::Result<()> {
2610 let http = self.http_client.clone();
2611 let sender = self.data_sender.clone();
2612 let instrument_id = request.single_instrument_id()?;
2613 let limit = request.limit.map(|n| n.get() as u32);
2614 let request_id = request.request_id;
2615 let client_id = request.client_id.unwrap_or(self.client_id);
2616 let params = request.params;
2617 let clock = self.clock;
2618 let start_nanos = datetime_to_unix_nanos(request.start);
2619 let end_nanos = datetime_to_unix_nanos(request.end);
2620 let start = request.start;
2621 let end = request.end;
2622 anyhow::ensure!(
2623 limit.is_none_or(|value| value <= 1000),
2624 "Binance Futures trade limit must not exceed 1000"
2625 );
2626
2627 self.spawn_command(async move {
2628 let result = if start.is_some() || end.is_some() {
2629 http.request_agg_trades(instrument_id, start, end, limit)
2630 .await
2631 } else {
2632 http.request_trades(instrument_id, limit).await
2633 };
2634
2635 match result.context("failed to request trades from Binance Futures") {
2636 Ok(trades) => {
2637 let response = DataResponse::Trades(TradesResponse::new(
2638 request_id,
2639 client_id,
2640 instrument_id,
2641 trades,
2642 start_nanos,
2643 end_nanos,
2644 clock.get_time_ns(),
2645 params,
2646 ));
2647
2648 if let Err(e) = sender.send(DataEvent::Response(response)) {
2649 log::error!("Failed to send trades response: {e}");
2650 }
2651 }
2652 Err(e) => log::error!("Trade request failed: {e:?}"),
2653 }
2654 });
2655
2656 Ok(())
2657 }
2658
2659 fn request_funding_rates(&self, request: RequestFundingRates) -> anyhow::Result<()> {
2660 let http = self.http_client.clone();
2661 let sender = self.data_sender.clone();
2662 let instrument_id = request.single_instrument_id()?;
2663 let start = request.start;
2664 let end = request.end;
2665 let limit = request.limit.map(|n| n.get() as u32);
2666 let request_id = request.request_id;
2667 let client_id = request.client_id.unwrap_or(self.client_id);
2668 let params = request.params;
2669 let clock = self.clock;
2670 let start_nanos = datetime_to_unix_nanos(start);
2671 let end_nanos = datetime_to_unix_nanos(end);
2672
2673 self.spawn_command(async move {
2674 match http
2675 .request_funding_rates(instrument_id, start, end, limit)
2676 .await
2677 .context("failed to request funding rates from Binance Futures")
2678 {
2679 Ok(funding_rates) => {
2680 let response = DataResponse::FundingRates(FundingRatesResponse::new(
2681 request_id,
2682 client_id,
2683 instrument_id,
2684 funding_rates,
2685 start_nanos,
2686 end_nanos,
2687 clock.get_time_ns(),
2688 params,
2689 ));
2690
2691 if let Err(e) = sender.send(DataEvent::Response(response)) {
2692 log::error!("Failed to send funding rates response: {e}");
2693 }
2694 }
2695 Err(e) => log::error!("Funding rates request failed for {instrument_id}: {e:?}"),
2696 }
2697 });
2698
2699 Ok(())
2700 }
2701
2702 fn request_bars(&self, request: RequestBars) -> anyhow::Result<()> {
2703 let http = self.http_client.clone();
2704 let sender = self.data_sender.clone();
2705 let bar_type = request.single_bar_type()?;
2706 let start = request.start;
2707 let end = request.end;
2708 let limit = request.limit.map(|n| n.get() as u32);
2709 let request_id = request.request_id;
2710 let client_id = request.client_id.unwrap_or(self.client_id);
2711 let params = request.params;
2712 let clock = self.clock;
2713 let start_nanos = datetime_to_unix_nanos(start);
2714 let end_nanos = datetime_to_unix_nanos(end);
2715 anyhow::ensure!(
2716 bar_type.aggregation_source() == AggregationSource::External,
2717 "Binance historical bars require EXTERNAL aggregation"
2718 );
2719 anyhow::ensure!(
2720 bar_type.spec().price_type == PriceType::Last,
2721 "Binance historical bars require LAST price type"
2722 );
2723 anyhow::ensure!(
2724 bar_type.spec().is_time_aggregated(),
2725 "Binance historical bars require time aggregation"
2726 );
2727
2728 self.spawn_command(async move {
2729 let result = http.request_bars(bar_type, start, end, limit).await;
2730
2731 match result.context("failed to request bars from Binance Futures") {
2732 Ok(bars) => {
2733 let response = DataResponse::Bars(BarsResponse::new(
2734 request_id,
2735 client_id,
2736 bar_type,
2737 bars,
2738 start_nanos,
2739 end_nanos,
2740 clock.get_time_ns(),
2741 params,
2742 ));
2743
2744 if let Err(e) = sender.send(DataEvent::Response(response)) {
2745 log::error!("Failed to send bars response: {e}");
2746 }
2747 }
2748 Err(e) => log::error!("Bar request failed: {e:?}"),
2749 }
2750 });
2751
2752 Ok(())
2753 }
2754
2755 fn request_book_snapshot(&self, request: RequestBookSnapshot) -> anyhow::Result<()> {
2756 let depth = request.depth.map_or(1000, |value| value.get() as u32);
2757 anyhow::ensure!(
2758 BINANCE_BOOK_DEPTHS.contains(&depth),
2759 "invalid Binance Futures order-book depth {depth}; valid values are {BINANCE_BOOK_DEPTHS:?}"
2760 );
2761 let http = self.http_client.clone();
2762 let book_sync = self.book_sync.clone();
2763 let sender = self.data_sender.clone();
2764 let instrument_id = request.single_instrument_id()?;
2765 let request_id = request.request_id;
2766 let client_id = request.client_id.unwrap_or(self.client_id);
2767 let params = request.params;
2768 let clock = self.clock;
2769
2770 self.spawn_command(async move {
2771 let permit = book_sync.pacer().acquire(depth_request_weight(depth)).await;
2772
2773 match http
2774 .request_book_snapshot_with_permit(instrument_id, Some(depth), Some(permit))
2775 .await
2776 {
2777 Ok(book) => {
2778 let response = DataResponse::Book(BookResponse::new(
2779 request_id,
2780 client_id,
2781 instrument_id,
2782 book,
2783 None,
2784 None,
2785 clock.get_time_ns(),
2786 params,
2787 ));
2788
2789 if let Err(e) = sender.send(DataEvent::Response(response)) {
2790 log::error!("Failed to send book snapshot response: {e}");
2791 }
2792 }
2793 Err(e) => log::error!("Book snapshot request failed for {instrument_id}: {e:?}"),
2794 }
2795 });
2796 Ok(())
2797 }
2798}
2799
2800impl BinanceFuturesDataClient {
2801 fn subscribe_book(&self, cmd: &SubscribeBookDeltas) -> anyhow::Result<()> {
2802 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2803 let cmd = cmd.with_instrument_ids(instrument_id);
2804 if cmd.book_type == BookType::L1_MBP {
2805 anyhow::ensure!(
2806 cmd.depth.is_none_or(|depth| depth.get() == 1),
2807 "Binance Futures L1_MBP supports depth 1 only"
2808 );
2809 anyhow::ensure!(
2810 !self.book_subscriptions.contains_key(&instrument_id),
2811 "cannot subscribe L1_MBP and L2_MBP for the same Binance Futures instrument"
2812 );
2813 self.l1_book_subscriptions.rcu(|subscriptions| {
2814 *subscriptions.entry(instrument_id).or_insert(0) += 1;
2815 });
2816
2817 self.subscribe_top_of_book(instrument_id);
2818 return Ok(());
2819 }
2820
2821 if cmd.book_type != BookType::L2_MBP {
2822 anyhow::bail!(
2823 "Binance Futures supports L1_MBP and L2_MBP order book subscriptions"
2824 );
2825 }
2826
2827 anyhow::ensure!(
2828 !self.l1_book_subscriptions.contains_key(&instrument_id),
2829 "cannot subscribe L1_MBP and L2_MBP for the same Binance Futures instrument"
2830 );
2831
2832 let depth = cmd.depth.map_or(1000, |d| d.get() as u32);
2833
2834 if !BINANCE_BOOK_DEPTHS.contains(&depth) {
2835 anyhow::bail!(
2836 "Invalid depth {depth} for Binance Futures order book. \
2837 Valid values: {BINANCE_BOOK_DEPTHS:?}"
2838 );
2839 }
2840
2841 if let Some(existing) = self.book_subscriptions.load().get(&instrument_id) {
2842 anyhow::ensure!(
2843 *existing == depth,
2844 "Binance Futures book depth cannot change while subscribed"
2845 );
2846 }
2847
2848 let stream = book_stream(&instrument_id, depth);
2851 revive_book_drains(&self.book_unsubscribes_pending, instrument_id, &stream);
2852
2853 self.book_subscriptions.insert(instrument_id, depth);
2854
2855 satisfy_book_drain(&self.book_unsubscribes_pending, instrument_id, &stream);
2858
2859 if is_partial_book_depth(depth) {
2860 let ws = self.ws_public_client.clone();
2861 self.spawn_ws(
2862 chain_command(&self.book_command_tail, async move {
2863 ws.subscribe(vec![stream])
2864 .await
2865 .context("book deltas subscription")
2866 }),
2867 "order book subscription",
2868 );
2869
2870 return Ok(());
2871 }
2872
2873 self.book_sync.subscribe(instrument_id);
2875
2876 let ws = self.ws_public_client.clone();
2878 self.spawn_ws(
2879 chain_command(&self.book_command_tail, async move {
2880 ws.subscribe(vec![stream])
2881 .await
2882 .context("book deltas subscription")
2883 }),
2884 "order book subscription",
2885 );
2886
2887 Ok(())
2888 })
2889 }
2890
2891 fn unsubscribe_book(&mut self, cmd: &UnsubscribeBookDeltas) -> anyhow::Result<()> {
2892 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2893 if let Some(count) = self
2894 .l1_book_subscriptions
2895 .load()
2896 .get(&instrument_id)
2897 .copied()
2898 {
2899 if count == 1 {
2900 self.l1_book_subscriptions.remove(&instrument_id);
2901 } else {
2902 self.l1_book_subscriptions.rcu(|subscriptions| {
2903 if let Some(existing) = subscriptions.get_mut(&instrument_id) {
2904 *existing -= 1;
2905 }
2906 });
2907 }
2908
2909 self.unsubscribe_top_of_book(instrument_id);
2910 return Ok(());
2911 }
2912
2913 let ws = self.ws_public_client.clone();
2914
2915 let Some(depth) = self.book_subscriptions.load().get(&instrument_id).copied() else {
2916 return Ok(());
2917 };
2918
2919 self.book_subscriptions.remove(&instrument_id);
2920
2921 self.book_sync.remove(instrument_id);
2923 let stream = book_stream(&instrument_id, depth);
2924 let generation = self.book_drain_generation;
2925 self.book_drain_generation += 1;
2926
2927 arm_book_drain(
2931 &self.book_unsubscribes_pending,
2932 instrument_id,
2933 generation,
2934 &stream,
2935 );
2936
2937 let book_unsubscribes_pending = self.book_unsubscribes_pending.clone();
2938 self.spawn_ws(
2939 chain_command(&self.book_command_tail, async move {
2940 let sent = ws
2941 .unsubscribe_correlated(vec![stream.clone()], generation)
2942 .await
2943 .context("book deltas unsubscribe");
2944
2945 match sent {
2946 Ok(sent) if sent.contains(&stream) => Ok(()),
2947 Ok(_) => {
2948 remove_book_drain(&book_unsubscribes_pending, generation);
2949 Ok(())
2950 }
2951 Err(e) => {
2952 remove_book_drain(&book_unsubscribes_pending, generation);
2953 Err(e)
2954 }
2955 }
2956 }),
2957 "order book unsubscribe",
2958 );
2959
2960 Ok(())
2961 })
2962 }
2963
2964 fn subscribe_top_of_book(&self, instrument_id: InstrumentId) {
2965 let should_subscribe = {
2966 let previous = self
2967 .quote_refs
2968 .load()
2969 .get(&instrument_id)
2970 .copied()
2971 .unwrap_or(0);
2972 self.quote_refs
2973 .rcu(|refs| *refs.entry(instrument_id).or_insert(0) += 1);
2974 previous == 0
2975 };
2976
2977 if should_subscribe {
2978 let ws = self.ws_public_client.clone();
2979 let stream = format!(
2980 "{}@bookTicker",
2981 format_binance_stream_symbol(&instrument_id)
2982 );
2983 self.spawn_ws(
2984 async move {
2985 ws.subscribe(vec![stream])
2986 .await
2987 .context("top-of-book subscription")
2988 },
2989 "top-of-book subscription",
2990 );
2991 }
2992 }
2993
2994 fn unsubscribe_top_of_book(&self, instrument_id: InstrumentId) {
2995 let should_unsubscribe = match self.quote_refs.load().get(&instrument_id).copied() {
2996 Some(1) => {
2997 self.quote_refs.remove(&instrument_id);
2998 true
2999 }
3000 Some(count) if count > 1 => {
3001 self.quote_refs.rcu(|refs| {
3002 if let Some(existing) = refs.get_mut(&instrument_id) {
3003 *existing -= 1;
3004 }
3005 });
3006 false
3007 }
3008 _ => false,
3009 };
3010
3011 if should_unsubscribe {
3012 let ws = self.ws_public_client.clone();
3013 let stream = format!(
3014 "{}@bookTicker",
3015 format_binance_stream_symbol(&instrument_id)
3016 );
3017 self.spawn_ws(
3018 async move {
3019 ws.unsubscribe(vec![stream])
3020 .await
3021 .context("top-of-book unsubscribe")
3022 .map(|_| ())
3023 },
3024 "top-of-book unsubscribe",
3025 );
3026 }
3027 }
3028}
3029
3030fn is_partial_book_depth(depth: u32) -> bool {
3031 matches!(depth, 5 | 10 | 20)
3032}
3033
3034fn book_stream(instrument_id: &InstrumentId, depth: u32) -> String {
3035 let symbol = format_binance_stream_symbol(instrument_id);
3036 if is_partial_book_depth(depth) {
3037 format!("{symbol}@depth{depth}@100ms")
3038 } else {
3039 format!("{symbol}@depth@0ms")
3040 }
3041}
3042
3043#[derive(Clone, Debug)]
3044struct BookDrain {
3045 generation: u64,
3046 stream: String,
3047 satisfied: bool,
3050}
3051
3052fn arm_book_drain(
3053 map: &AtomicMap<InstrumentId, Vec<BookDrain>>,
3054 instrument_id: InstrumentId,
3055 generation: u64,
3056 stream: &str,
3057) {
3058 map.rcu(|m| {
3059 m.entry(instrument_id).or_default().push(BookDrain {
3060 generation,
3061 stream: stream.to_owned(),
3062 satisfied: false,
3063 });
3064 });
3065}
3066
3067fn satisfy_book_drain(
3068 map: &AtomicMap<InstrumentId, Vec<BookDrain>>,
3069 instrument_id: InstrumentId,
3070 stream: &str,
3071) {
3072 map.rcu(|m| {
3073 if let Some(drains) = m.get_mut(&instrument_id) {
3074 for drain in drains.iter_mut().filter(|drain| drain.stream == stream) {
3075 drain.satisfied = true;
3076 }
3077 }
3078 });
3079}
3080
3081fn remove_book_drain(map: &AtomicMap<InstrumentId, Vec<BookDrain>>, generation: u64) {
3084 map.rcu(|m| {
3085 for drains in m.values_mut() {
3086 drains.retain(|drain| drain.generation != generation);
3087 }
3088 m.retain(|_, drains| !drains.is_empty());
3089 });
3090}
3091
3092fn book_drain_active(
3093 map: &AtomicMap<InstrumentId, Vec<BookDrain>>,
3094 instrument_id: InstrumentId,
3095) -> bool {
3096 map.load()
3097 .get(&instrument_id)
3098 .is_some_and(|drains| drains.iter().any(|drain| !drain.satisfied))
3099}
3100
3101fn revive_book_drains(
3105 map: &AtomicMap<InstrumentId, Vec<BookDrain>>,
3106 instrument_id: InstrumentId,
3107 stream: &str,
3108) {
3109 map.rcu(|m| {
3110 if let Some(drains) = m.get_mut(&instrument_id) {
3111 for drain in drains.iter_mut().filter(|drain| drain.stream != stream) {
3112 drain.satisfied = false;
3113 }
3114 }
3115 });
3116}
3117
3118fn subscribe_ticker(client: &BinanceFuturesDataClient, data_type: &DataType) -> anyhow::Result<()> {
3119 let instrument_id = BinanceFuturesDataClient::required_instrument_id_metadata(data_type)?;
3120 if instrument_id.venue != client.venue() {
3121 anyhow::bail!(
3122 "Binance Futures ticker custom data requires BINANCE venue instrument, received {instrument_id}"
3123 );
3124 }
3125
3126 let should_subscribe = {
3127 let prev = client
3128 .ticker_refs
3129 .load()
3130 .get(&instrument_id)
3131 .copied()
3132 .unwrap_or(0);
3133 client.ticker_refs.rcu(|m| {
3134 let count = m.entry(instrument_id).or_insert(0);
3135 *count += 1;
3136 });
3137 prev == 0
3138 };
3139
3140 if should_subscribe {
3141 let ws = client.ws_client.clone();
3142 let stream = ticker_stream(&instrument_id);
3143 client.spawn_ws(
3144 async move {
3145 ws.subscribe(vec![stream])
3146 .await
3147 .context("ticker subscription")
3148 },
3149 "ticker subscription",
3150 );
3151 }
3152
3153 Ok(())
3154}
3155
3156fn unsubscribe_ticker(
3157 client: &BinanceFuturesDataClient,
3158 data_type: &DataType,
3159) -> anyhow::Result<()> {
3160 let instrument_id = BinanceFuturesDataClient::required_instrument_id_metadata(data_type)?;
3161 if instrument_id.venue != client.venue() {
3162 anyhow::bail!(
3163 "Binance Futures ticker custom data requires BINANCE venue instrument, received {instrument_id}"
3164 );
3165 }
3166
3167 let should_unsubscribe = {
3168 let prev = client.ticker_refs.load().get(&instrument_id).copied();
3169 match prev {
3170 Some(count) if count <= 1 => {
3171 client.ticker_refs.remove(&instrument_id);
3172 true
3173 }
3174 Some(_) => {
3175 client.ticker_refs.rcu(|m| {
3176 if let Some(count) = m.get_mut(&instrument_id) {
3177 *count = count.saturating_sub(1);
3178 }
3179 });
3180 false
3181 }
3182 None => false,
3183 }
3184 };
3185
3186 if should_unsubscribe {
3187 let ws = client.ws_client.clone();
3188 let stream = ticker_stream(&instrument_id);
3189 client.spawn_ws(
3190 async move {
3191 ws.unsubscribe(vec![stream])
3192 .await
3193 .context("ticker unsubscribe")
3194 .map(|_| ())
3195 },
3196 "ticker unsubscribe",
3197 );
3198 }
3199
3200 Ok(())
3201}
3202
3203fn ticker_data_type(instrument_id: InstrumentId) -> DataType {
3204 let metadata = Params::new(
3205 [(
3206 "instrument_id".to_string(),
3207 serde_json::Value::String(instrument_id.to_string()),
3208 )]
3209 .into(),
3210 );
3211 DataType::new(
3212 "BinanceFuturesTicker",
3213 Some(metadata),
3214 Some(instrument_id.to_string()),
3215 )
3216}
3217
3218fn mark_price_data_type(instrument_id: InstrumentId) -> DataType {
3219 let metadata = Params::new(
3220 [(
3221 "instrument_id".to_string(),
3222 serde_json::Value::String(instrument_id.to_string()),
3223 )]
3224 .into(),
3225 );
3226 DataType::new(
3227 "BinanceFuturesMarkPriceUpdate",
3228 Some(metadata),
3229 Some(instrument_id.to_string()),
3230 )
3231}
3232
3233fn ticker_stream(instrument_id: &InstrumentId) -> String {
3234 format!("{}@ticker", format_binance_stream_symbol(instrument_id))
3235}
3236
3237#[cfg(test)]
3238mod tests {
3239 use rstest::rstest;
3240 use rust_decimal_macros::dec;
3241
3242 use super::*;
3243
3244 #[rstest]
3245 fn test_parse_order_book_snapshot_skips_invalid_levels() {
3246 let instrument_id = InstrumentId::from("BTCUSDT-PERP.BINANCE");
3247 let order_book = BinanceOrderBook {
3248 last_update_id: 10,
3249 bids: vec![
3250 ("not-a-price".to_string(), "1.0".to_string()),
3251 ("100.00".to_string(), "0.5".to_string()),
3252 ],
3253 asks: vec![
3254 ("101.00".to_string(), "not-a-quantity".to_string()),
3255 ("102.00".to_string(), "0.7".to_string()),
3256 ],
3257 event_time: None,
3258 transaction_time: None,
3259 };
3260
3261 let deltas =
3262 parse_order_book_snapshot(&order_book, instrument_id, 2, 3, UnixNanos::from(1));
3263
3264 assert_eq!(deltas.deltas.len(), 3);
3265 assert_eq!(deltas.deltas[1].order.side, OrderSide::Buy.into());
3266 assert_eq!(deltas.deltas[1].order.price.as_decimal(), dec!(100.00));
3267 assert_eq!(deltas.deltas[1].order.size.as_decimal(), dec!(0.500));
3268 assert_eq!(deltas.deltas[2].order.side, OrderSide::Sell.into());
3269 assert_eq!(deltas.deltas[2].order.price.as_decimal(), dec!(102.00));
3270 assert_eq!(deltas.deltas[2].order.size.as_decimal(), dec!(0.700));
3271 assert_eq!(deltas.deltas[1].flags, RecordFlag::F_SNAPSHOT as u8);
3272 assert_eq!(
3273 deltas.deltas[2].flags,
3274 RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8
3275 );
3276 assert_eq!(deltas.ts_event, UnixNanos::from(1));
3277 assert_eq!(deltas.ts_init, UnixNanos::from(1));
3278 }
3279
3280 #[rstest]
3281 #[case::negative(-1)]
3282 #[case::overflow(i64::MAX)]
3283 fn test_parse_order_book_snapshot_falls_back_for_invalid_timestamp(
3284 #[case] transaction_time: i64,
3285 ) {
3286 let order_book = BinanceOrderBook {
3287 last_update_id: 10,
3288 bids: vec![],
3289 asks: vec![],
3290 event_time: None,
3291 transaction_time: Some(transaction_time),
3292 };
3293
3294 let ts_init = UnixNanos::from(1);
3295 let deltas = parse_order_book_snapshot(
3296 &order_book,
3297 InstrumentId::from("BTCUSDT-PERP.BINANCE"),
3298 2,
3299 3,
3300 ts_init,
3301 );
3302
3303 assert_eq!(deltas.ts_event, ts_init);
3304 assert_eq!(deltas.ts_init, ts_init);
3305 }
3306
3307 #[rstest]
3308 fn test_parse_order_book_snapshot_all_invalid_levels_marks_clear_last() {
3309 let instrument_id = InstrumentId::from("BTCUSDT-PERP.BINANCE");
3310 let order_book = BinanceOrderBook {
3311 last_update_id: 10,
3312 bids: vec![("not-a-price".to_string(), "1.0".to_string())],
3313 asks: vec![("101.00".to_string(), "not-a-quantity".to_string())],
3314 event_time: None,
3315 transaction_time: None,
3316 };
3317
3318 let deltas =
3319 parse_order_book_snapshot(&order_book, instrument_id, 2, 3, UnixNanos::from(1));
3320
3321 assert_eq!(deltas.deltas.len(), 1);
3322 assert_eq!(deltas.deltas[0].action, BookAction::Clear);
3323 assert_eq!(
3324 deltas.deltas[0].flags,
3325 RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8
3326 );
3327 }
3328
3329 #[rstest]
3330 fn test_book_drain_gate_follows_unsatisfied_entries() {
3331 let map = AtomicMap::new();
3332 let instrument_id = InstrumentId::from("BTCUSDT-PERP.BINANCE");
3333
3334 assert!(!book_drain_active(&map, instrument_id));
3335 arm_book_drain(&map, instrument_id, 1, "btcusdt@depth20@100ms");
3336 assert!(book_drain_active(&map, instrument_id));
3337
3338 satisfy_book_drain(&map, instrument_id, "btcusdt@depth20@100ms");
3339 assert!(!book_drain_active(&map, instrument_id));
3340
3341 arm_book_drain(&map, instrument_id, 2, "btcusdt@depth10@100ms");
3342 assert!(book_drain_active(&map, instrument_id));
3343 }
3344
3345 #[rstest]
3346 fn test_remove_book_drain_resolves_only_matching_generation() {
3347 let map = AtomicMap::new();
3348 let instrument_id = InstrumentId::from("BTCUSDT-PERP.BINANCE");
3349
3350 arm_book_drain(&map, instrument_id, 1, "btcusdt@depth20@100ms");
3353 satisfy_book_drain(&map, instrument_id, "btcusdt@depth20@100ms");
3354 arm_book_drain(&map, instrument_id, 2, "btcusdt@depth20@100ms");
3355
3356 remove_book_drain(&map, 1);
3357 assert!(book_drain_active(&map, instrument_id));
3358
3359 remove_book_drain(&map, 2);
3360 assert!(!book_drain_active(&map, instrument_id));
3361 assert!(!map.load().contains_key(&instrument_id));
3362 }
3363
3364 #[rstest]
3365 fn test_semantics_change_revives_satisfied_drains() {
3366 let map = AtomicMap::new();
3367 let instrument_id = InstrumentId::from("BTCUSDT-PERP.BINANCE");
3368
3369 arm_book_drain(&map, instrument_id, 1, "btcusdt@depth20@100ms");
3370 satisfy_book_drain(&map, instrument_id, "btcusdt@depth20@100ms");
3371 assert!(!book_drain_active(&map, instrument_id));
3372
3373 revive_book_drains(&map, instrument_id, "btcusdt@depth5@100ms");
3376 assert!(book_drain_active(&map, instrument_id));
3377
3378 satisfy_book_drain(&map, instrument_id, "btcusdt@depth20@100ms");
3380 revive_book_drains(&map, instrument_id, "btcusdt@depth20@100ms");
3381 assert!(!book_drain_active(&map, instrument_id));
3382 }
3383
3384 #[rstest]
3385 fn test_remove_book_drain_leaves_other_generations_pending() {
3386 let map = AtomicMap::new();
3387 let instrument_id = InstrumentId::from("BTCUSDT-PERP.BINANCE");
3388
3389 arm_book_drain(&map, instrument_id, 1, "btcusdt@depth20@100ms");
3390 arm_book_drain(&map, instrument_id, 2, "btcusdt@depth10@100ms");
3391
3392 remove_book_drain(&map, 2);
3394 assert!(book_drain_active(&map, instrument_id));
3395
3396 remove_book_drain(&map, 1);
3397 assert!(!book_drain_active(&map, instrument_id));
3398 }
3399
3400 #[rstest]
3401 #[case::smallest(5, 2)]
3402 #[case::tier_one_max(50, 2)]
3403 #[case::tier_two_min(51, 5)]
3404 #[case::tier_two_max(100, 5)]
3405 #[case::tier_three_min(101, 10)]
3406 #[case::tier_three_max(500, 10)]
3407 #[case::tier_four_min(501, 20)]
3408 #[case::largest(1000, 20)]
3409 fn test_depth_request_weight_follows_venue_tiers(#[case] limit: u32, #[case] expected: u32) {
3410 assert_eq!(depth_request_weight(limit), expected);
3411 }
3412
3413 #[rstest]
3414 #[case::network(BinanceFuturesHttpError::NetworkError("connection reset".to_string()), true)]
3415 #[case::server_error(
3416 BinanceFuturesHttpError::UnexpectedStatus {
3417 status: 503,
3418 body: String::new(),
3419 retry_after: None,
3420 },
3421 true
3422 )]
3423 #[case::rate_limited(
3424 BinanceFuturesHttpError::BinanceError {
3425 code: -1003,
3426 message: "Too many requests".to_string(),
3427 status: 429,
3428 retry_after: None,
3429 },
3430 true
3431 )]
3432 #[case::retry_budget_exceeded(
3433 BinanceFuturesHttpError::RetryBudgetExceeded("elapsed budget exhausted".to_string()),
3434 true
3435 )]
3436 #[case::invalid_symbol(
3437 BinanceFuturesHttpError::BinanceError {
3438 code: -1121,
3439 message: "Invalid symbol.".to_string(),
3440 status: 400,
3441 retry_after: None,
3442 },
3443 false
3444 )]
3445 fn test_depth_snapshot_error_retries_transient_failures(
3446 #[case] error: BinanceFuturesHttpError,
3447 #[case] retryable: bool,
3448 ) {
3449 let instrument_id = InstrumentId::from("BTCUSDT-PERP.BINANCE");
3450 let message = format!("depth snapshot request for {instrument_id} failed: {error}");
3451
3452 let classified = depth_snapshot_error(instrument_id, &error);
3453
3454 let expected = if retryable {
3455 BinanceBookError::Retryable(message)
3456 } else {
3457 BinanceBookError::Permanent(message)
3458 };
3459
3460 assert_eq!(classified, expected);
3461 }
3462}