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