Skip to main content

nautilus_binance/futures/
data.rs

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