Skip to main content

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