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