Skip to main content

nautilus_okx/
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 OKX adapter.
17
18use std::sync::{
19    Arc,
20    atomic::{AtomicBool, AtomicU64, Ordering},
21};
22
23use ahash::{AHashMap, AHashSet};
24use anyhow::Context;
25use futures_util::{StreamExt, pin_mut};
26use nautilus_common::{
27    cache::quote::QuoteCache,
28    clients::{DataClient, execute_bar_subscriptions, execute_instrument_subscriptions},
29    live::{
30        dst::time::{self, Duration, Instant},
31        runner::get_data_event_sender,
32        sender::EventSender,
33    },
34    messages::{
35        DataEvent,
36        data::{
37            BarsResponse, BookResponse, DataRequestFailed, DataResponse, DataResponseEnvelope,
38            FundingRatesResponse, InstrumentResponse, InstrumentsResponse,
39            OptionChainReferencePriceResponse, RequestBars, RequestBookSnapshot,
40            RequestFundingRates, RequestInstrument, RequestInstruments,
41            RequestOptionChainReferencePrice, RequestTrades, SubscribeBars, SubscribeBookDeltas,
42            SubscribeBookDepth, SubscribeFundingRates, SubscribeIndexPrices, SubscribeInstrument,
43            SubscribeInstrumentStatus, SubscribeInstruments, SubscribeMarkPrices,
44            SubscribeOptionGreeks, SubscribeQuotes, SubscribeTrades, TradesResponse,
45            UnsubscribeBars, UnsubscribeBookDeltas, UnsubscribeBookDepth, UnsubscribeFundingRates,
46            UnsubscribeIndexPrices, UnsubscribeInstrument, UnsubscribeInstrumentStatus,
47            UnsubscribeMarkPrices, UnsubscribeOptionGreeks, UnsubscribeQuotes, UnsubscribeTrades,
48        },
49    },
50};
51use nautilus_core::{
52    AtomicMap, AtomicSet, Params, UUID4, UnixNanos,
53    datetime::datetime_to_unix_nanos,
54    env::get_or_env_var,
55    time::{AtomicTime, get_atomic_clock_realtime},
56};
57use nautilus_live::{
58    SocketControl,
59    book::snapshot::snapshot_expired,
60    task::{TaskGroup, TaskGroupGuard, TaskSpawner},
61};
62use nautilus_model::{
63    data::{Data, FundingRateUpdate, InstrumentStatus},
64    enums::{BookType, GreeksConvention, MarketStatusAction},
65    identifiers::{ClientId, InstrumentId, Venue},
66    instruments::{Instrument, InstrumentAny},
67};
68use ustr::Ustr;
69
70use crate::{
71    book::{
72        BookChannelScope, BookSequenceOutcome,
73        recovery::{spawn_recovery_monitor, spawn_recovery_task, start_recovery},
74        sync::BookSyncTracker,
75    },
76    common::{
77        consts::{
78            OKX_VENUE, OKX_WS_HEARTBEAT_SECS, contract_filter_with_config_types,
79            resolve_book_depth, resolve_instrument_families, select_book_channel,
80        },
81        enums::{
82            OKXBookAction, OKXBookChannel, OKXGreeksType, OKXInstrumentStatus, OKXInstrumentType,
83            OKXVipLevel,
84        },
85        models::OKXInstrument,
86        parse::{
87            extract_inst_family, instrument_definitions_match, okx_instrument_type_from_symbol,
88            okx_status_to_market_action, parse_base_quote_from_symbol, parse_instrument_any,
89            parse_instrument_id, parse_millisecond_timestamp, parse_price, parse_quantity,
90        },
91        task::{spawn_task, terminate_tasks},
92    },
93    config::OKXDataClientConfig,
94    http::{
95        client::{OKXHistoryCoverage, OKXHttpClient, OKXInstrumentDefinitionError},
96        query::GetSpreadsParams,
97    },
98    websocket::{
99        client::OKXWebSocketClient,
100        enums::OKXWsChannel,
101        error::OKXWsError,
102        handler::SnapshotGate,
103        messages::{NautilusWsMessage, OKXBookMsg, OKXOptionSummaryMsg, OKXWsMessage},
104        parse::{
105            extract_fees_from_cached_instrument, parse_book_depth_msg, parse_book_msg_vec,
106            parse_index_price_msg_vec, parse_option_summary_greeks, parse_rpi_book_msg_vec,
107            parse_ws_message_data,
108        },
109    },
110};
111
112const BOOK_SNAPSHOT_DEPTH: usize = 5;
113
114#[derive(Debug)]
115pub struct OKXDataClient {
116    client_id: ClientId,
117    config: OKXDataClientConfig,
118    http_client: OKXHttpClient,
119    ws_public: Option<OKXWebSocketClient>,
120    ws_business: Option<OKXWebSocketClient>,
121    is_connected: AtomicBool,
122    transports_started: bool,
123    tasks: TaskGroup,
124    data_sender: EventSender<DataEvent>,
125    // Shared instrument cache keyed by raw symbol so stream tasks, reconciliation,
126    // and request paths all read and write one source of truth
127    instruments_by_symbol: Arc<AtomicMap<Ustr, InstrumentAny>>,
128    // Serializes instrument diff-update-publish sequences between the stream
129    // tasks and the refresh task; only held for synchronous sections
130    instrument_update_lock: Arc<InstrumentUpdateLock>,
131    book_channels: Arc<AtomicMap<InstrumentId, OKXBookChannel>>,
132    book_sync: BookSyncTracker,
133    book_deltas: Arc<AtomicSet<InstrumentId>>,
134    book_depths: Arc<AtomicMap<InstrumentId, usize>>,
135    index_ticker_map: Arc<AtomicMap<Ustr, AHashSet<Ustr>>>,
136    option_greeks_subs: Arc<AtomicMap<InstrumentId, AHashSet<OKXGreeksType>>>,
137    // `Mutex<AHashMap>` so the spawned subscribe task can roll back the
138    // refcount on failure. A bare `AHashMap` would leave the count
139    // permanently incremented and wedge future Greeks subscribes.
140    option_summary_family_subs: Arc<parking_lot::Mutex<AHashMap<Ustr, usize>>>,
141    clock: &'static AtomicTime,
142}
143
144impl OKXDataClient {
145    /// Creates a new [`OKXDataClient`] instance.
146    ///
147    /// # Errors
148    ///
149    /// Returns an error if the client fails to initialize.
150    pub fn new(client_id: ClientId, config: OKXDataClientConfig) -> anyhow::Result<Self> {
151        config.validate()?;
152
153        let clock = get_atomic_clock_realtime();
154        let data_sender = get_data_event_sender();
155        let api_key = config
156            .api_key
157            .as_ref()
158            .map(|value| value.expose_secret().to_owned());
159        let api_secret = config
160            .api_secret
161            .as_ref()
162            .map(|value| value.expose_secret().to_owned());
163        let api_passphrase = config
164            .api_passphrase
165            .as_ref()
166            .map(|value| value.expose_secret().to_owned());
167        let proxy_url = config
168            .proxy_url
169            .as_ref()
170            .map(|value| value.expose_secret().to_owned());
171
172        let http_client = if config.has_api_credentials() {
173            OKXHttpClient::with_credentials(
174                api_key.clone(),
175                api_secret.clone(),
176                api_passphrase.clone(),
177                Some(config.http_base_url()),
178                config.http_timeout_secs,
179                config.max_retries,
180                config.retry_delay_initial_ms,
181                config.retry_delay_max_ms,
182                config.environment,
183                proxy_url.clone(),
184            )?
185        } else {
186            OKXHttpClient::new(
187                Some(config.http_base_url()),
188                config.http_timeout_secs,
189                config.max_retries,
190                config.retry_delay_initial_ms,
191                config.retry_delay_max_ms,
192                config.environment,
193                proxy_url.clone(),
194            )?
195        };
196
197        let (ws_api_key, ws_api_secret, ws_api_passphrase) = if config
198            .vip_level
199            .is_some_and(|level| level >= OKXVipLevel::Vip4)
200        {
201            (
202                Some(get_or_env_var(api_key, "OKX_API_KEY")?),
203                Some(get_or_env_var(api_secret, "OKX_API_SECRET")?),
204                Some(get_or_env_var(api_passphrase, "OKX_API_PASSPHRASE")?),
205            )
206        } else {
207            (None, None, None)
208        };
209
210        let ws_public = OKXWebSocketClient::new(
211            Some(config.ws_public_url()),
212            ws_api_key,
213            ws_api_secret,
214            ws_api_passphrase,
215            None,
216            Some(OKX_WS_HEARTBEAT_SECS),
217            None,
218            config.transport_backend,
219            proxy_url.clone(),
220        )
221        .context("failed to construct OKX public websocket client")?
222        .with_socket_control(SocketControl::new(
223            client_id,
224            Some(*OKX_VENUE),
225            "okx-public-data-streams",
226        ));
227
228        let ws_business = if config.requires_business_ws() {
229            let ws = OKXWebSocketClient::new(
230                Some(config.ws_business_url()),
231                None, // No auth needed for public business channels
232                None,
233                None,
234                None,
235                Some(OKX_WS_HEARTBEAT_SECS),
236                None,
237                config.transport_backend,
238                proxy_url,
239            )
240            .context("failed to construct OKX business websocket client")?
241            .with_socket_control(SocketControl::new(
242                client_id,
243                Some(*OKX_VENUE),
244                "okx-business-data-streams",
245            ));
246            Some(ws)
247        } else {
248            None
249        };
250
251        if let Some(vip_level) = config.vip_level {
252            ws_public.set_vip_level(vip_level);
253
254            if let Some(ref ws) = ws_business {
255                ws.set_vip_level(vip_level);
256            }
257        }
258
259        Ok(Self {
260            client_id,
261            config,
262            http_client,
263            ws_public: Some(ws_public),
264            ws_business,
265            is_connected: AtomicBool::new(false),
266            transports_started: false,
267            tasks: TaskGroup::new(),
268            data_sender,
269            instruments_by_symbol: Arc::new(AtomicMap::new()),
270            instrument_update_lock: Arc::new(InstrumentUpdateLock::default()),
271            book_channels: Arc::new(AtomicMap::new()),
272            book_sync: BookSyncTracker::default(),
273            book_deltas: Arc::new(AtomicSet::new()),
274            book_depths: Arc::new(AtomicMap::new()),
275            index_ticker_map: Arc::new(AtomicMap::new()),
276            option_greeks_subs: Arc::new(AtomicMap::new()),
277            option_summary_family_subs: Arc::new(parking_lot::Mutex::new(AHashMap::new())),
278            clock,
279        })
280    }
281
282    fn venue(&self) -> Venue {
283        *OKX_VENUE
284    }
285
286    fn vip_level(&self) -> Option<OKXVipLevel> {
287        self.ws_public.as_ref().map(OKXWebSocketClient::vip_level)
288    }
289
290    fn public_ws(&self) -> anyhow::Result<&OKXWebSocketClient> {
291        self.ws_public
292            .as_ref()
293            .context("public websocket client not initialized")
294    }
295
296    fn business_ws(&self) -> anyhow::Result<&OKXWebSocketClient> {
297        self.ws_business
298            .as_ref()
299            .context("business websocket client not available (credentials required)")
300    }
301
302    fn send_data(sender: &EventSender<DataEvent>, data: Data) {
303        if let Err(e) = sender.send(DataEvent::Data(data)) {
304            log::error!("Failed to emit data event: {e}");
305        }
306    }
307
308    fn send_book_depth(
309        messages: &mut [OKXBookMsg],
310        instrument: &InstrumentAny,
311        subscriptions: &AtomicMap<InstrumentId, usize>,
312        sender: &EventSender<DataEvent>,
313        ts_init: UnixNanos,
314        spread: bool,
315    ) {
316        let Some(limit) = subscriptions.get_cloned(&instrument.id()) else {
317            return;
318        };
319
320        let result = messages
321            .iter_mut()
322            .map(|message| {
323                if spread {
324                    for level in message.bids.iter_mut().chain(&mut message.asks) {
325                        level.orders_count = level.liquidated_orders_count.clone();
326                    }
327                }
328
329                let mut depth = parse_book_depth_msg(
330                    message,
331                    instrument.id(),
332                    instrument.price_precision(),
333                    instrument.size_precision(),
334                    ts_init,
335                )?;
336                depth.bids.truncate(limit);
337                depth.asks.truncate(limit);
338                depth.bid_counts.truncate(limit);
339                depth.ask_counts.truncate(limit);
340                Ok(Data::BookDepth(Box::new(depth)))
341            })
342            .collect::<anyhow::Result<Vec<_>>>();
343
344        match result {
345            Ok(data) => {
346                for item in data {
347                    Self::send_data(sender, item);
348                }
349            }
350            Err(e) => log::error!("Failed to parse book depth: {e}"),
351        }
352    }
353
354    fn book_channel(
355        &self,
356        instrument_id: InstrumentId,
357        depth: Option<std::num::NonZeroUsize>,
358        params: Option<&Params>,
359    ) -> OKXBookChannel {
360        if self.http_client.is_spread(instrument_id) {
361            // Spreads have no incremental book channel; sprd-books5 pushes a full
362            // 5-level snapshot, emitted as F_SNAPSHOT deltas to feed the book.
363            return OKXBookChannel::SprdBooks5;
364        }
365
366        let raw_depth = depth.map_or(0, std::num::NonZero::get);
367        let depth = resolve_book_depth(raw_depth);
368        if depth != raw_depth {
369            log::debug!("Clamped book depth {raw_depth} to {depth} (OKX supports 50 or 400)");
370        }
371
372        let rpi = params
373            .and_then(|params| params.get_bool("rpi"))
374            .unwrap_or(false);
375        let vip = self.vip_level().unwrap_or(OKXVipLevel::Vip0);
376
377        if rpi {
378            OKXBookChannel::BooksRpi
379        } else {
380            let channel = select_book_channel(depth, vip);
381            if depth == 50 && channel == OKXBookChannel::Book {
382                log::debug!(
383                    "VIP level {vip} insufficient for 50-depth channel, falling back to default"
384                );
385            }
386
387            channel
388        }
389    }
390
391    fn unsubscribe_book_channel(&self, instrument_id: InstrumentId) -> anyhow::Result<()> {
392        if self.http_client.is_spread(instrument_id) {
393            let ws = self.business_ws()?.clone();
394            self.book_channels.remove(&instrument_id);
395            self.book_sync.remove(instrument_id);
396            self.spawn_ws(
397                async move {
398                    ws.unsubscribe_spread_book(instrument_id)
399                        .await
400                        .context("spread book unsubscribe")
401                },
402                "spread book unsubscribe",
403            );
404
405            return Ok(());
406        }
407
408        let ws = self.public_ws()?.clone();
409        let channel = self.book_channels.get_cloned(&instrument_id);
410        self.book_channels.remove(&instrument_id);
411        self.book_sync.remove(instrument_id);
412
413        self.spawn_ws(
414            async move {
415                match channel {
416                    Some(OKXBookChannel::Books50L2Tbt) => ws
417                        .unsubscribe_book50_l2_tbt(instrument_id)
418                        .await
419                        .context("books50-l2-tbt unsubscribe")?,
420                    Some(OKXBookChannel::BookL2Tbt) => ws
421                        .unsubscribe_book_l2_tbt(instrument_id)
422                        .await
423                        .context("books-l2-tbt unsubscribe")?,
424                    Some(OKXBookChannel::Book) => ws
425                        .unsubscribe_book(instrument_id)
426                        .await
427                        .context("book unsubscribe")?,
428                    Some(OKXBookChannel::BooksRpi) => ws
429                        .unsubscribe_book_rpi(instrument_id)
430                        .await
431                        .context("books-rpi unsubscribe")?,
432                    Some(OKXBookChannel::SprdBooks5) => ws
433                        .unsubscribe_book(instrument_id)
434                        .await
435                        .context("book unsubscribe")?,
436                    None => {
437                        log::warn!(
438                            "Book channel not found for {instrument_id}; unsubscribing fallback channel"
439                        );
440                        ws.unsubscribe_book(instrument_id)
441                            .await
442                            .context("book fallback unsubscribe")?;
443                    }
444                }
445
446                Ok(())
447            },
448            "order book unsubscribe",
449        );
450
451        Ok(())
452    }
453
454    fn subscribe_book_channel(
455        &self,
456        instrument_id: InstrumentId,
457        channel: OKXBookChannel,
458    ) -> anyhow::Result<()> {
459        if let Some(active) = self.book_channels.get_cloned(&instrument_id) {
460            anyhow::ensure!(
461                active == channel,
462                "Conflicting OKX book channel for {instrument_id}: active {active:?}, requested {channel:?}"
463            );
464            return Ok(());
465        }
466
467        let ws = if channel == OKXBookChannel::SprdBooks5 {
468            self.business_ws()?.clone()
469        } else {
470            self.public_ws()?.clone()
471        };
472
473        let spawner = self.tasks.spawner()?;
474        let gate = SnapshotGate::default();
475        gate.lock().close();
476        self.book_channels.insert(instrument_id, channel);
477        let cancel =
478            self.book_sync
479                .record_subscription(instrument_id, Instant::now(), gate.clone());
480        let guard = cancel.clone().drop_guard();
481        let tracker = self.book_sync.clone();
482        let timeout = Duration::from_secs(self.config.book_snapshot_timeout_secs);
483        spawn_task(&spawner.clone(), async move {
484            let _guard = guard;
485            let result = ws
486                .subscribe_book_channel(instrument_id, channel, cancel.clone(), gate)
487                .await;
488
489            if cancel.is_cancelled() {
490                return;
491            }
492
493            match result {
494                Ok(()) => {
495                    if !snapshot_expired(&cancel, timeout).await {
496                        return;
497                    }
498
499                    log::warn!(
500                        "Initial book snapshot missing for {instrument_id}; requesting a fresh snapshot"
501                    );
502                }
503                Err(e) => {
504                    log::warn!("Initial book subscription send failed for {instrument_id}: {e}");
505                }
506            }
507
508            if let Some(recovery) = tracker.claim_subscription_recovery(instrument_id, &cancel) {
509                spawn_recovery_task(instrument_id, channel, recovery, ws, timeout, &spawner);
510            }
511        });
512
513        Ok(())
514    }
515
516    fn spawn_ws<F>(&self, fut: F, context: &'static str)
517    where
518        F: Future<Output = anyhow::Result<()>> + Send + 'static,
519    {
520        let fut = async move {
521            if let Err(e) = fut.await {
522                log::error!("{context}: {e:?}");
523            }
524        };
525        self.spawn_task(fut);
526    }
527
528    fn spawn_task<F>(&self, fut: F)
529    where
530        F: Future<Output = ()> + Send + 'static,
531    {
532        match self.tasks.spawner() {
533            Ok(spawner) => spawn_task(&spawner, fut),
534            Err(e) => log::debug!("Skipping task after OKX shutdown began: {e}"),
535        }
536    }
537
538    fn begin_generation_shutdown(&self) {
539        self.tasks.begin_shutdown();
540        self.is_connected.store(false, Ordering::Release);
541
542        if let Some(ws) = self.ws_public.as_ref() {
543            ws.begin_shutdown();
544        }
545
546        if let Some(ws) = self.ws_business.as_ref() {
547            ws.begin_shutdown();
548        }
549    }
550
551    fn register_book_health_monitor(&self) -> anyhow::Result<()> {
552        let interval_duration = Duration::from_secs(self.config.book_stale_check_interval_secs);
553        let threshold = Duration::from_secs(self.config.book_stale_threshold_secs);
554
555        if interval_duration.is_zero() || threshold.is_zero() {
556            return Ok(());
557        }
558
559        let book_sync = self.book_sync.clone();
560        let tasks = self
561            .tasks
562            .spawner()
563            .context("OKX data task admission is closed")?;
564        let cancel = tasks.cancellation_token();
565
566        tasks.spawn(async move {
567            let mut interval = time::interval(interval_duration);
568
569            loop {
570                tokio::select! {
571                    biased;
572                    () = cancel.cancelled() => {
573                        log::debug!("Book health monitor task cancelled");
574                        break;
575                    }
576                    _ = interval.tick() => {
577                        for signal in book_sync.stale_books(threshold, Instant::now()) {
578                            signal.log();
579                        }
580                    }
581                }
582            }
583        })?;
584        Ok(())
585    }
586
587    #[expect(clippy::too_many_arguments)]
588    fn handle_ws_message(
589        message: OKXWsMessage,
590        data_sender: &EventSender<DataEvent>,
591        instruments_by_symbol: &Arc<AtomicMap<Ustr, InstrumentAny>>,
592        http_client: &OKXHttpClient,
593        config: &OKXDataClientConfig,
594        instrument_update_lock: &InstrumentUpdateLock,
595        book_channels: &Arc<AtomicMap<InstrumentId, OKXBookChannel>>,
596        book_sync: &BookSyncTracker,
597        book_depths: &AtomicMap<InstrumentId, usize>,
598        book_deltas: &AtomicSet<InstrumentId>,
599        recovery_ws: Option<&OKXWebSocketClient>,
600        business_ws: Option<&OKXWebSocketClient>,
601        quote_cache: &mut QuoteCache,
602        funding_cache: &mut AHashMap<Ustr, (Ustr, u64)>,
603        index_ticker_map: &Arc<AtomicMap<Ustr, AHashSet<Ustr>>>,
604        option_greeks_subs: &Arc<AtomicMap<InstrumentId, AHashSet<OKXGreeksType>>>,
605        book_channel_scope: BookChannelScope,
606        snapshot_timeout: Duration,
607        tasks: &TaskSpawner,
608        clock: &AtomicTime,
609    ) {
610        // Book recovery must run on the socket that owns the failed channel:
611        // the public websocket for market-data books, the business websocket
612        // for spread books.
613        let recovery_ws = match book_channel_scope {
614            BookChannelScope::Public => recovery_ws,
615            BookChannelScope::Business => business_ws,
616        };
617
618        match message {
619            OKXWsMessage::BookData {
620                arg,
621                action,
622                mut data,
623            } => {
624                let Some(inst_id) = arg.inst_id else {
625                    log::warn!("Book data without inst_id");
626                    return;
627                };
628                let instruments_guard = instruments_by_symbol.load();
629                let Some(instrument) = instruments_guard.get(&inst_id) else {
630                    log::warn!("No cached instrument for book data: {inst_id}");
631                    return;
632                };
633                let ts_init = clock.get_time_ns();
634
635                if arg.channel == OKXWsChannel::Books5 {
636                    if action == OKXBookAction::Snapshot {
637                        Self::send_book_depth(
638                            &mut data,
639                            instrument,
640                            book_depths,
641                            data_sender,
642                            ts_init,
643                            false,
644                        );
645                    }
646
647                    return;
648                }
649
650                let sequences = data
651                    .iter()
652                    .map(|msg| (msg.prev_seq_id, msg.seq_id))
653                    .collect::<Vec<_>>();
654
655                let data: Vec<_> = data
656                    .into_iter()
657                    .filter(|msg| {
658                        action == OKXBookAction::Snapshot
659                            || !msg.bids.is_empty()
660                            || !msg.asks.is_empty()
661                    })
662                    .collect();
663
664                match parse_book_msg_vec(
665                    data,
666                    &instrument.id(),
667                    instrument.price_precision(),
668                    instrument.size_precision(),
669                    action,
670                    ts_init,
671                ) {
672                    Ok(data_vec) => {
673                        let outcome = book_sync.validate_sequence_if_subscribed(
674                            book_channels,
675                            instrument.id(),
676                            action == OKXBookAction::Snapshot,
677                            &sequences,
678                            Instant::now(),
679                        );
680
681                        if !handle_book_sequence_outcome(
682                            outcome,
683                            instrument.id(),
684                            book_channels,
685                            book_sync,
686                            recovery_ws,
687                            snapshot_timeout,
688                            tasks,
689                        ) {
690                            return;
691                        }
692
693                        for data in data_vec {
694                            Self::send_data(data_sender, data);
695                        }
696                    }
697                    Err(e) => {
698                        log::error!("Failed to parse book data: {e}");
699                        start_recovery(
700                            instrument.id(),
701                            book_channels,
702                            book_sync,
703                            recovery_ws,
704                            snapshot_timeout,
705                            tasks,
706                        );
707                    }
708                }
709            }
710            OKXWsMessage::RpiBookData { arg, action, data } => {
711                let Some(inst_id) = arg.inst_id else {
712                    log::warn!("RPI book data without inst_id");
713                    return;
714                };
715                let instruments_guard = instruments_by_symbol.load();
716                let Some(instrument) = instruments_guard.get(&inst_id) else {
717                    log::warn!("No cached instrument for RPI book data: {inst_id}");
718                    return;
719                };
720                let ts_init = clock.get_time_ns();
721                let sequences = data
722                    .iter()
723                    .map(|msg| (Some(msg.prev_seq_id), msg.seq_id))
724                    .collect::<Vec<_>>();
725
726                let data: Vec<_> = data
727                    .into_iter()
728                    .filter(|msg| {
729                        action == OKXBookAction::Snapshot
730                            || !msg.bids.is_empty()
731                            || !msg.asks.is_empty()
732                    })
733                    .collect();
734
735                match parse_rpi_book_msg_vec(
736                    data,
737                    &instrument.id(),
738                    instrument.price_precision(),
739                    instrument.size_precision(),
740                    action,
741                    ts_init,
742                ) {
743                    Ok(data_vec) => {
744                        let outcome = book_sync.validate_sequence_if_subscribed(
745                            book_channels,
746                            instrument.id(),
747                            action == OKXBookAction::Snapshot,
748                            &sequences,
749                            Instant::now(),
750                        );
751
752                        if !handle_book_sequence_outcome(
753                            outcome,
754                            instrument.id(),
755                            book_channels,
756                            book_sync,
757                            recovery_ws,
758                            snapshot_timeout,
759                            tasks,
760                        ) {
761                            return;
762                        }
763
764                        for data in data_vec {
765                            Self::send_data(data_sender, data);
766                        }
767                    }
768                    Err(e) => {
769                        log::error!("Failed to parse RPI book data: {e}");
770                        start_recovery(
771                            instrument.id(),
772                            book_channels,
773                            book_sync,
774                            recovery_ws,
775                            snapshot_timeout,
776                            tasks,
777                        );
778                    }
779                }
780            }
781            OKXWsMessage::ChannelData {
782                channel,
783                inst_id,
784                data,
785            } => {
786                // Option summary subscriptions use instFamily (not instId), so
787                // the arg has inst_id: None. Each element in the data array carries
788                // its own inst_id that we resolve per-message.
789                if matches!(channel, OKXWsChannel::OptionSummary) {
790                    let ts_init = clock.get_time_ns();
791
792                    match serde_json::from_value::<Vec<OKXOptionSummaryMsg>>(data) {
793                        Ok(msgs) => {
794                            let subs = option_greeks_subs.load();
795                            let instruments_guard = instruments_by_symbol.load();
796
797                            for msg in &msgs {
798                                let Some(instrument) = instruments_guard.get(&msg.inst_id) else {
799                                    continue;
800                                };
801                                let instrument_id = instrument.id();
802                                let Some(conventions) = subs.get(&instrument_id) else {
803                                    continue;
804                                };
805
806                                for greeks_type in conventions {
807                                    match parse_option_summary_greeks(
808                                        msg,
809                                        &instrument_id,
810                                        *greeks_type,
811                                        ts_init,
812                                    ) {
813                                        Ok(greeks) => {
814                                            if let Err(e) = data_sender
815                                                .send(DataEvent::Data(Data::OptionGreeks(greeks)))
816                                            {
817                                                log::error!(
818                                                    "Failed to emit option greeks event: {e}"
819                                                );
820                                            }
821                                        }
822                                        Err(e) => {
823                                            log::error!(
824                                                "Failed to parse option summary for {} ({greeks_type:?}): {e}",
825                                                msg.inst_id
826                                            );
827                                        }
828                                    }
829                                }
830                            }
831                        }
832                        Err(e) => {
833                            log::error!("Failed to deserialize option summary data: {e}");
834                        }
835                    }
836                    return;
837                }
838
839                let Some(inst_id) = inst_id else {
840                    log::debug!("Channel data without inst_id: {channel:?}");
841                    return;
842                };
843
844                // Index tickers use base pair format (e.g., "BTC-USDT") but instruments
845                // are keyed by full symbol (e.g., "BTC-USDT-SWAP"). Dispatch index price
846                // updates only to instruments that subscribed via subscribe_index_prices.
847                if matches!(channel, OKXWsChannel::IndexTickers) {
848                    let ts_init = clock.get_time_ns();
849                    let map_guard = index_ticker_map.load();
850                    let Some(subscribed_symbols) = map_guard.get(&inst_id) else {
851                        log::debug!("No subscribed instruments for index ticker: {inst_id}");
852                        return;
853                    };
854
855                    let mut symbols: Vec<Ustr> = subscribed_symbols.iter().copied().collect();
856
857                    // Sort the fan-out; the subscribed set iterates in per-process hash order
858                    symbols.sort();
859
860                    drop(map_guard);
861
862                    let instruments_guard = instruments_by_symbol.load();
863
864                    for sym in &symbols {
865                        let Some(instrument) = instruments_guard.get(sym) else {
866                            log::warn!("No cached instrument for index ticker symbol: {sym}");
867                            continue;
868                        };
869
870                        match parse_index_price_msg_vec(
871                            data.clone(),
872                            &instrument.id(),
873                            instrument.price_precision(),
874                            ts_init,
875                        ) {
876                            Ok(data_vec) => {
877                                for d in data_vec {
878                                    Self::send_data(data_sender, d);
879                                }
880                            }
881                            Err(e) => log::error!("Failed to parse index price data: {e}"),
882                        }
883                    }
884                    return;
885                }
886
887                let instruments_guard = instruments_by_symbol.load();
888                let Some(instrument) = instruments_guard.get(&inst_id) else {
889                    log::warn!("No cached instrument for {channel:?}: {inst_id}");
890                    return;
891                };
892                let instrument_id = instrument.id();
893                let price_precision = instrument.price_precision();
894                let size_precision = instrument.size_precision();
895                let ts_init = clock.get_time_ns();
896
897                if channel == OKXWsChannel::Books5 {
898                    match serde_json::from_value::<Vec<OKXBookMsg>>(data) {
899                        Ok(mut messages) => Self::send_book_depth(
900                            &mut messages,
901                            instrument,
902                            book_depths,
903                            data_sender,
904                            ts_init,
905                            false,
906                        ),
907                        Err(e) => log::error!("Failed to deserialize book depth: {e}"),
908                    }
909
910                    return;
911                }
912
913                if matches!(channel, OKXWsChannel::SprdBooks5) {
914                    let mut msgs: Vec<OKXBookMsg> = match serde_json::from_value(data) {
915                        Ok(m) => m,
916                        Err(e) => {
917                            log::error!("Failed to deserialize spread book data: {e}");
918                            return;
919                        }
920                    };
921
922                    Self::send_book_depth(
923                        &mut msgs,
924                        instrument,
925                        book_depths,
926                        data_sender,
927                        ts_init,
928                        true,
929                    );
930
931                    match parse_book_msg_vec(
932                        msgs,
933                        &instrument_id,
934                        price_precision,
935                        size_precision,
936                        OKXBookAction::Snapshot,
937                        ts_init,
938                    ) {
939                        Ok(data_vec) => {
940                            if !book_sync.record_snapshot_if_subscribed(
941                                book_channels,
942                                instrument_id,
943                                Instant::now(),
944                            ) {
945                                return;
946                            }
947
948                            if !book_deltas.contains(&instrument_id) {
949                                return;
950                            }
951
952                            for data in data_vec {
953                                Self::send_data(data_sender, data);
954                            }
955                        }
956                        Err(e) => {
957                            log::error!("Failed to parse spread book data: {e}");
958                            start_recovery(
959                                instrument_id,
960                                book_channels,
961                                book_sync,
962                                recovery_ws,
963                                snapshot_timeout,
964                                tasks,
965                            );
966                        }
967                    }
968
969                    return;
970                }
971
972                if matches!(channel, OKXWsChannel::BboTbt | OKXWsChannel::SprdBboTbt) {
973                    let msgs: Vec<OKXBookMsg> = match serde_json::from_value(data) {
974                        Ok(m) => m,
975                        Err(e) => {
976                            log::error!("Failed to deserialize BboTbt data: {e}");
977                            return;
978                        }
979                    };
980
981                    for msg in &msgs {
982                        let bid = msg.bids.first();
983                        let ask = msg.asks.first();
984                        let bid_price =
985                            bid.and_then(|e| parse_price(&e.price, price_precision).ok());
986                        let bid_size =
987                            bid.and_then(|e| parse_quantity(&e.size, size_precision).ok());
988                        let ask_price =
989                            ask.and_then(|e| parse_price(&e.price, price_precision).ok());
990                        let ask_size =
991                            ask.and_then(|e| parse_quantity(&e.size, size_precision).ok());
992                        let ts_event = parse_millisecond_timestamp(msg.ts);
993
994                        match quote_cache.process(
995                            instrument_id,
996                            bid_price,
997                            ask_price,
998                            bid_size,
999                            ask_size,
1000                            ts_event,
1001                            ts_init,
1002                        ) {
1003                            Ok(quote) => Self::send_data(data_sender, Data::Quote(quote)),
1004                            Err(e) => {
1005                                log::debug!("Skipping partial BboTbt for {instrument_id}: {e}");
1006                            }
1007                        }
1008                    }
1009
1010                    return;
1011                }
1012
1013                match parse_ws_message_data(
1014                    &channel,
1015                    data,
1016                    &instrument_id,
1017                    price_precision,
1018                    size_precision,
1019                    ts_init,
1020                    funding_cache,
1021                    &instruments_guard,
1022                ) {
1023                    Ok(Some(ws_msg)) => {
1024                        dispatch_parsed_data(ws_msg, data_sender, instruments_by_symbol);
1025                    }
1026                    Ok(None) => {}
1027                    Err(e) => log::error!("Failed to parse {channel:?} data: {e}"),
1028                }
1029            }
1030            OKXWsMessage::Instruments(okx_instruments) => {
1031                let ts_init = clock.get_time_ns();
1032                // Hold the instrument lock for the batch so a concurrent
1033                // reconciliation cannot interleave diff, cache update, and publish
1034                let _update_guard = instrument_update_lock.mutex.lock();
1035
1036                for okx_inst in okx_instruments {
1037                    let inst_key = okx_inst.inst_id;
1038                    let cached = instruments_by_symbol.get_cloned(&inst_key);
1039                    let (margin_init, margin_maint) =
1040                        cached.as_ref().map_or((None, None), |instrument| {
1041                            extract_fees_from_cached_instrument(instrument)
1042                        });
1043                    let status_action = okx_status_to_market_action(okx_inst.state);
1044                    let is_live = matches!(okx_inst.state, OKXInstrumentStatus::Live);
1045                    match parse_instrument_any(&okx_inst, margin_init, margin_maint, ts_init) {
1046                        Ok(Some(inst_any)) => {
1047                            let instrument_id = inst_any.id();
1048                            let is_new_or_changed = cached.is_none_or(|cached| {
1049                                !instrument_definitions_match(&cached, &inst_any)
1050                            });
1051
1052                            if is_new_or_changed
1053                                && definition_in_scope(config, &okx_inst, &inst_any)
1054                            {
1055                                publish_instrument_updates(
1056                                    std::slice::from_ref(&inst_any),
1057                                    instruments_by_symbol,
1058                                    http_client,
1059                                    recovery_ws,
1060                                    business_ws,
1061                                    instrument_update_lock,
1062                                    data_sender,
1063                                );
1064                            }
1065
1066                            emit_instrument_status(
1067                                data_sender,
1068                                instrument_id,
1069                                status_action,
1070                                is_live,
1071                                ts_init,
1072                            );
1073                        }
1074                        Ok(None) => {
1075                            let instrument_id = instruments_by_symbol
1076                                .get_cloned(&inst_key)
1077                                .map_or_else(|| parse_instrument_id(inst_key), |i| i.id());
1078                            emit_instrument_status(
1079                                data_sender,
1080                                instrument_id,
1081                                status_action,
1082                                is_live,
1083                                ts_init,
1084                            );
1085                        }
1086                        Err(e) => {
1087                            log::warn!("Failed to parse instrument {}: {e}", okx_inst.inst_id);
1088                            let instrument_id = instruments_by_symbol
1089                                .get_cloned(&inst_key)
1090                                .map_or_else(|| parse_instrument_id(inst_key), |i| i.id());
1091                            emit_instrument_status(
1092                                data_sender,
1093                                instrument_id,
1094                                status_action,
1095                                is_live,
1096                                ts_init,
1097                            );
1098                        }
1099                    }
1100                }
1101            }
1102            OKXWsMessage::Orders(_)
1103            | OKXWsMessage::SpreadOrders(_)
1104            | OKXWsMessage::AlgoOrders(_)
1105            | OKXWsMessage::OrderResponse { .. }
1106            | OKXWsMessage::Account(_)
1107            | OKXWsMessage::Positions(_)
1108            | OKXWsMessage::LiquidationWarnings(_)
1109            | OKXWsMessage::SendFailed { .. } => {
1110                log::debug!("Ignoring execution message on data client");
1111            }
1112            OKXWsMessage::SubscriptionFailed {
1113                channel,
1114                inst_id,
1115                code,
1116                msg,
1117            } => {
1118                let book_instrument_id = inst_id
1119                    .filter(|_| channel.is_book())
1120                    .and_then(|inst_id| instruments_by_symbol.get_cloned(&inst_id))
1121                    .map(|instrument| instrument.id())
1122                    .filter(|instrument_id| {
1123                        book_channels
1124                            .get_cloned(instrument_id)
1125                            .is_some_and(|selected| {
1126                                crate::websocket::client::ws_channel_for_book(selected) == channel
1127                            })
1128                    });
1129
1130                // Book recovery retries a rejected book subscription and reports its own failure
1131                let Some(instrument_id) = book_instrument_id else {
1132                    log::error!(
1133                        "OKX rejected {channel:?} subscription for {inst_id:?} \
1134                         (code={code}, msg={msg}); no data will flow for this subscription"
1135                    );
1136                    return;
1137                };
1138
1139                log::warn!(
1140                    "OKX rejected {channel:?} subscription for {instrument_id} (code={code}, \
1141                     msg={msg}); recovering the book"
1142                );
1143
1144                let error = OKXWsError::OkxError {
1145                    error_code: code,
1146                    message: msg,
1147                };
1148
1149                if book_sync.reject_recovery(instrument_id, error) {
1150                    return;
1151                }
1152
1153                start_recovery(
1154                    instrument_id,
1155                    book_channels,
1156                    book_sync,
1157                    recovery_ws,
1158                    snapshot_timeout,
1159                    tasks,
1160                );
1161            }
1162            OKXWsMessage::Error(_) => {}
1163            OKXWsMessage::Reconnected => {
1164                log::info!("Websocket reconnected");
1165                quote_cache.clear();
1166                funding_cache.clear();
1167
1168                book_sync.reset_sequences(book_channels, book_channel_scope);
1169
1170                if !snapshot_timeout.is_zero() {
1171                    let pending_count = book_sync.seed_pending_snapshots(
1172                        book_channels,
1173                        book_channel_scope,
1174                        snapshot_timeout,
1175                        Instant::now(),
1176                    );
1177
1178                    if pending_count > 0 {
1179                        spawn_recovery_monitor(
1180                            book_sync.clone(),
1181                            recovery_ws.cloned(),
1182                            Arc::clone(book_channels),
1183                            book_channel_scope,
1184                            snapshot_timeout,
1185                            tasks,
1186                        );
1187                    }
1188                }
1189            }
1190            OKXWsMessage::Authenticated => {
1191                log::debug!("Websocket authenticated");
1192            }
1193        }
1194    }
1195
1196    /// Establishes instrument context and both WebSocket transports.
1197    ///
1198    /// Any failure leaves partially started transports for [`Self::teardown_transports`].
1199    async fn connect_session(&mut self) -> anyhow::Result<()> {
1200        // Reset leaves the old generation canceled until this async boundary can drain it
1201        if self.transports_started
1202            || !self.tasks.is_empty()
1203            || !self.tasks.is_open()
1204            || self
1205                .ws_public
1206                .as_ref()
1207                .is_some_and(OKXWebSocketClient::has_task)
1208            || self
1209                .ws_business
1210                .as_ref()
1211                .is_some_and(OKXWebSocketClient::has_task)
1212        {
1213            self.teardown_transports().await?;
1214        }
1215
1216        if !self.tasks.is_open() {
1217            self.tasks
1218                .start_generation()
1219                .context("failed to start OKX data task generation")?;
1220        }
1221        self.transports_started = true;
1222
1223        let all_instruments = fetch_configured_instruments(&self.http_client, &self.config).await?;
1224
1225        // Diff before updating the cache so reconnects do not republish
1226        // unchanged definitions; the writer tasks start after this point,
1227        // so no instrument lock is needed here
1228        let changed = changed_definitions(&all_instruments, &self.instruments_by_symbol);
1229
1230        self.instruments_by_symbol.rcu(|m| {
1231            for instrument in &all_instruments {
1232                m.insert(instrument.symbol().inner(), instrument.clone());
1233            }
1234        });
1235
1236        // Cache both websockets before connecting and before publishing, so
1237        // every cache holds a definition before it is emitted
1238        let instruments: Vec<_> = self
1239            .instruments_by_symbol
1240            .load()
1241            .values()
1242            .cloned()
1243            .collect();
1244
1245        if let Some(ref ws) = self.ws_public {
1246            ws.cache_instruments(&instruments);
1247        }
1248
1249        if let Some(ref ws) = self.ws_business {
1250            ws.cache_instruments(&instruments);
1251        }
1252
1253        publish_instrument_updates(
1254            &changed,
1255            &self.instruments_by_symbol,
1256            &self.http_client,
1257            self.ws_public.as_ref(),
1258            self.ws_business.as_ref(),
1259            &self.instrument_update_lock,
1260            &self.data_sender,
1261        );
1262
1263        let instrument_types = configured_instrument_types(&self.config);
1264
1265        if let Some(ref mut ws) = self.ws_public {
1266            ws.connect()
1267                .await
1268                .context("failed to connect OKX public websocket")?;
1269            ws.wait_until_active(10.0)
1270                .await
1271                .context("public websocket did not become active")?;
1272
1273            let stream = ws.stream();
1274            let sender = self.data_sender.clone();
1275            let insts = self.instruments_by_symbol.clone();
1276            let http = self.http_client.clone();
1277            let config = self.config.clone();
1278            let update_lock = self.instrument_update_lock.clone();
1279            let book_channels = self.book_channels.clone();
1280            let book_sync = self.book_sync.clone();
1281            let book_depths = self.book_depths.clone();
1282            let book_deltas = self.book_deltas.clone();
1283            let recovery_ws = ws.clone();
1284            let business_ws = self.ws_business.clone();
1285            let idx_map = self.index_ticker_map.clone();
1286            let greeks_subs = self.option_greeks_subs.clone();
1287            let tasks = self
1288                .tasks
1289                .spawner()
1290                .context("OKX data task admission is closed")?;
1291            let task_spawner = tasks.clone();
1292            let cancel = tasks.cancellation_token();
1293            let snapshot_timeout = Duration::from_secs(self.config.book_snapshot_timeout_secs);
1294            let clock = self.clock;
1295
1296            tasks
1297                .spawn(async move {
1298                    let mut quote_cache = QuoteCache::new();
1299                    let mut funding_cache: AHashMap<Ustr, (Ustr, u64)> = AHashMap::new();
1300
1301                    pin_mut!(stream);
1302
1303                    loop {
1304                        tokio::select! {
1305                            biased;
1306                            () = cancel.cancelled() => {
1307                                log::debug!("Public websocket stream task cancelled");
1308                                break;
1309                            }
1310                            Some(message) = stream.next() => {
1311                                Self::handle_ws_message(
1312                                    message,
1313                                    &sender,
1314                                    &insts,
1315                                    &http,
1316                                    &config,
1317                                    &update_lock,
1318                                    &book_channels,
1319                                    &book_sync,
1320                                    &book_depths,
1321                                    &book_deltas,
1322                                    Some(&recovery_ws),
1323                                    business_ws.as_ref(),
1324                                    &mut quote_cache,
1325                                    &mut funding_cache,
1326                                    &idx_map,
1327                                    &greeks_subs,
1328                                    BookChannelScope::Public,
1329                                    snapshot_timeout,
1330                                    &task_spawner,
1331                                    clock,
1332                                );
1333                            }
1334                        }
1335                    }
1336                })
1337                .context("failed to register OKX public WebSocket stream task")?;
1338
1339            for inst_type in &instrument_types {
1340                ws.subscribe_instruments(*inst_type)
1341                    .await
1342                    .with_context(|| {
1343                        format!("failed to subscribe to instrument type {inst_type:?}")
1344                    })?;
1345            }
1346        }
1347
1348        if let Some(ref mut ws) = self.ws_business {
1349            ws.connect()
1350                .await
1351                .context("failed to connect OKX business websocket")?;
1352            ws.wait_until_active(10.0)
1353                .await
1354                .context("business websocket did not become active")?;
1355
1356            let stream = ws.stream();
1357            let sender = self.data_sender.clone();
1358            let insts = self.instruments_by_symbol.clone();
1359            let http = self.http_client.clone();
1360            let config = self.config.clone();
1361            let update_lock = self.instrument_update_lock.clone();
1362            let book_channels = self.book_channels.clone();
1363            let book_sync = self.book_sync.clone();
1364            let book_depths = self.book_depths.clone();
1365            let book_deltas = self.book_deltas.clone();
1366            let business_ws = ws.clone();
1367            let idx_map = self.index_ticker_map.clone();
1368            let greeks_subs = self.option_greeks_subs.clone();
1369            let tasks = self
1370                .tasks
1371                .spawner()
1372                .context("OKX data task admission is closed")?;
1373            let task_spawner = tasks.clone();
1374            let cancel = tasks.cancellation_token();
1375            let snapshot_timeout = Duration::from_secs(self.config.book_snapshot_timeout_secs);
1376            let clock = self.clock;
1377
1378            tasks
1379                .spawn(async move {
1380                    let mut quote_cache = QuoteCache::new();
1381                    let mut funding_cache: AHashMap<Ustr, (Ustr, u64)> = AHashMap::new();
1382
1383                    pin_mut!(stream);
1384
1385                    loop {
1386                        tokio::select! {
1387                            biased;
1388                            () = cancel.cancelled() => {
1389                                log::debug!("Business websocket stream task cancelled");
1390                                break;
1391                            }
1392                            Some(message) = stream.next() => {
1393                                Self::handle_ws_message(
1394                                    message,
1395                                    &sender,
1396                                    &insts,
1397                                    &http,
1398                                    &config,
1399                                    &update_lock,
1400                                    &book_channels,
1401                                    &book_sync,
1402                                    &book_depths,
1403                                    &book_deltas,
1404                                    None,
1405                                    Some(&business_ws),
1406                                    &mut quote_cache,
1407                                    &mut funding_cache,
1408                                    &idx_map,
1409                                    &greeks_subs,
1410                                    BookChannelScope::Business,
1411                                    snapshot_timeout,
1412                                    &task_spawner,
1413                                    clock,
1414                                );
1415                            }
1416                        }
1417                    }
1418                })
1419                .context("failed to register OKX business WebSocket stream task")?;
1420        }
1421
1422        self.register_book_health_monitor()?;
1423        self.register_instrument_refresh()?;
1424        Ok(())
1425    }
1426
1427    /// Spawns the periodic instrument reconciliation task, disabled when the
1428    /// configured interval is zero. The handle is tracked in `self.tasks`, so
1429    /// `teardown_transports` joins it and the cancellation token stops it on
1430    /// disconnect, failed connect, stop, and dispose.
1431    fn register_instrument_refresh(&self) -> anyhow::Result<()> {
1432        let minutes = self.config.update_instruments_interval_mins;
1433
1434        if minutes == 0 {
1435            log::debug!("Instrument refresh disabled (update_instruments_interval_mins=0)");
1436            return Ok(());
1437        }
1438
1439        let interval = Duration::from_secs(minutes.saturating_mul(60));
1440        let tasks = self
1441            .tasks
1442            .spawner()
1443            .context("OKX data task admission is closed")?;
1444        let cancel = tasks.cancellation_token();
1445        let http_client = self.http_client.clone();
1446        let config = self.config.clone();
1447        let instruments = self.instruments_by_symbol.clone();
1448        let update_lock = self.instrument_update_lock.clone();
1449        let ws_public = self.ws_public.clone();
1450        let ws_business = self.ws_business.clone();
1451        let data_sender = self.data_sender.clone();
1452        let client_id = self.client_id;
1453
1454        tasks.spawn(async move {
1455            loop {
1456                let sleep = time::sleep(interval);
1457                tokio::pin!(sleep);
1458
1459                tokio::select! {
1460                    biased;
1461                    () = cancel.cancelled() => break,
1462                    () = &mut sleep => {}
1463                }
1464
1465                let result = tokio::select! {
1466                    biased;
1467                    () = cancel.cancelled() => break,
1468                    result = reconcile_instruments(
1469                        &http_client,
1470                        &config,
1471                        &instruments,
1472                        &update_lock,
1473                        ws_public.as_ref(),
1474                        ws_business.as_ref(),
1475                        &data_sender,
1476                    ) => result,
1477                };
1478
1479                match result {
1480                    Ok(summary) => {
1481                        log::debug!(
1482                            "OKX instruments refreshed: client_id={client_id}, fetched={}, changed={}, missing={}",
1483                            summary.fetched,
1484                            summary.changed,
1485                            summary.missing,
1486                        );
1487                    }
1488                    Err(e) => {
1489                        log::warn!(
1490                            "Failed to refresh OKX instruments: client_id={client_id}, error={e:?}"
1491                        );
1492                    }
1493                }
1494            }
1495
1496            log::debug!("Instrument refresh task cancelled");
1497        })?;
1498        Ok(())
1499    }
1500
1501    /// Cancels stream tasks, closes both WebSocket transports, and clears
1502    /// transport-local subscription bookkeeping.
1503    ///
1504    /// Safe to call after a partially failed connect and idempotent.
1505    async fn teardown_transports(&mut self) -> anyhow::Result<()> {
1506        self.transports_started = false;
1507        self.begin_generation_shutdown();
1508
1509        if let Some(ws) = self.ws_public.as_ref() {
1510            ws.request_close().await;
1511        }
1512
1513        if let Some(ws) = self.ws_business.as_ref() {
1514            ws.request_close().await;
1515        }
1516
1517        let task_result = terminate_tasks(&self.tasks, "OKX data client").await;
1518
1519        let public_result = if let Some(ref mut ws) = self.ws_public {
1520            ws.close().await.context("failed to close public websocket")
1521        } else {
1522            Ok(())
1523        };
1524
1525        let business_result = if let Some(ref mut ws) = self.ws_business {
1526            ws.close()
1527                .await
1528                .context("failed to close business websocket")
1529        } else {
1530            Ok(())
1531        };
1532
1533        self.book_deltas.store(AHashSet::new());
1534        self.book_depths.store(AHashMap::new());
1535        self.book_channels.store(AHashMap::new());
1536        self.book_sync.clear();
1537        self.option_greeks_subs
1538            .store(AHashMap::<InstrumentId, AHashSet<OKXGreeksType>>::new());
1539        self.option_summary_family_subs.lock().clear();
1540        self.is_connected.store(false, Ordering::Release);
1541
1542        let mut errors = Vec::new();
1543        if let Err(e) = task_result {
1544            errors.push(e.to_string());
1545        }
1546
1547        if let Err(e) = public_result {
1548            errors.push(e.to_string());
1549        }
1550
1551        if let Err(e) = business_result {
1552            errors.push(e.to_string());
1553        }
1554
1555        if errors.is_empty() {
1556            Ok(())
1557        } else {
1558            anyhow::bail!(errors.join("; "))
1559        }
1560    }
1561}
1562
1563fn handle_book_sequence_outcome(
1564    outcome: BookSequenceOutcome,
1565    instrument_id: InstrumentId,
1566    book_channels: &Arc<AtomicMap<InstrumentId, OKXBookChannel>>,
1567    book_sync: &BookSyncTracker,
1568    recovery_ws: Option<&OKXWebSocketClient>,
1569    snapshot_timeout: Duration,
1570    tasks: &TaskSpawner,
1571) -> bool {
1572    match outcome {
1573        BookSequenceOutcome::Accept => true,
1574        BookSequenceOutcome::Suppress => false,
1575        BookSequenceOutcome::Recover => {
1576            start_recovery(
1577                instrument_id,
1578                book_channels,
1579                book_sync,
1580                recovery_ws,
1581                snapshot_timeout,
1582                tasks,
1583            );
1584            false
1585        }
1586    }
1587}
1588
1589/// Guards instrument definitions: serializes diff-update-publish sequences
1590/// between writer tasks, and counts completed update batches so a pass can
1591/// detect a write that raced its fetch and skip publishing a stale snapshot.
1592#[derive(Debug, Default)]
1593struct InstrumentUpdateLock {
1594    mutex: parking_lot::Mutex<()>,
1595    write_seq: AtomicU64,
1596}
1597
1598/// The event for a historical response, by whether OKX covered the requested window: a covered
1599/// window completes the response envelope, so the data engine can write it back to a catalog; a
1600/// window the page cap cut short fails the request with the rows fetched, so the requester can
1601/// retry with smaller windows; otherwise a plain response, as a retry would not recover more.
1602fn history_event(
1603    request_id: UUID4,
1604    response: DataResponse,
1605    coverage: OKXHistoryCoverage,
1606) -> DataEvent {
1607    match coverage {
1608        OKXHistoryCoverage::Complete => completed_response(response),
1609        OKXHistoryCoverage::Truncated => DataEvent::RequestFailed(DataRequestFailed {
1610            request_id,
1611            reason: "OKX page limit reached before the start of the window".to_string(),
1612            response: Some(response),
1613        }),
1614        OKXHistoryCoverage::Unverified => DataEvent::Response(response),
1615    }
1616}
1617
1618fn completed_response(response: DataResponse) -> DataEvent {
1619    DataEvent::ResponseEnvelope(DataResponseEnvelope::new(response, true, None))
1620}
1621
1622/// The event that completes a request whose HTTP fetch failed.
1623fn request_failure(request_id: UUID4, error: &anyhow::Error) -> DataEvent {
1624    DataEvent::RequestFailed(DataRequestFailed {
1625        request_id,
1626        reason: format!("{error:#}"),
1627        response: None,
1628    })
1629}
1630
1631fn dispatch_parsed_data(
1632    msg: NautilusWsMessage,
1633    data_sender: &EventSender<DataEvent>,
1634    instruments_by_symbol: &Arc<AtomicMap<Ustr, InstrumentAny>>,
1635) {
1636    match msg {
1637        NautilusWsMessage::Data(payloads) => {
1638            for data in payloads {
1639                if let Err(e) = data_sender.send(DataEvent::Data(data)) {
1640                    log::error!("Failed to emit data event: {e}");
1641                }
1642            }
1643        }
1644        NautilusWsMessage::Deltas(deltas) => {
1645            let data = Data::BookDeltas(Box::new(deltas));
1646            if let Err(e) = data_sender.send(DataEvent::Data(data)) {
1647                log::error!("Failed to emit data event: {e}");
1648            }
1649        }
1650        NautilusWsMessage::FundingRates(updates) => {
1651            emit_funding_rates(data_sender, updates);
1652        }
1653        NautilusWsMessage::Instrument(instrument, status) => {
1654            instruments_by_symbol.insert(instrument.symbol().inner(), *instrument);
1655
1656            if let Some(status) = status
1657                && let Err(e) = data_sender.send(DataEvent::Data(Data::InstrumentStatus(status)))
1658            {
1659                log::error!("Failed to emit instrument status event: {e}");
1660            }
1661        }
1662        NautilusWsMessage::InstrumentStatus(status) => {
1663            if let Err(e) = data_sender.send(DataEvent::Data(Data::InstrumentStatus(status))) {
1664                log::error!("Failed to emit instrument status event: {e}");
1665            }
1666        }
1667        _ => {}
1668    }
1669}
1670
1671fn emit_funding_rates(sender: &EventSender<DataEvent>, updates: Vec<FundingRateUpdate>) {
1672    for update in updates {
1673        if let Err(e) = sender.send(DataEvent::Data(Data::FundingRate(update))) {
1674            log::error!("Failed to emit funding rate event: {e}");
1675        }
1676    }
1677}
1678
1679fn emit_instrument_status(
1680    sender: &EventSender<DataEvent>,
1681    instrument_id: InstrumentId,
1682    status_action: MarketStatusAction,
1683    is_live: bool,
1684    ts_init: UnixNanos,
1685) {
1686    let status = InstrumentStatus::new(
1687        instrument_id,
1688        status_action,
1689        ts_init,
1690        ts_init,
1691        None,
1692        None,
1693        Some(is_live),
1694        None,
1695        None,
1696    );
1697
1698    if let Err(e) = sender.send(DataEvent::Data(Data::InstrumentStatus(status))) {
1699        log::error!("Failed to emit instrument status event: {e}");
1700    }
1701}
1702
1703fn changed_definitions(
1704    fetched: &[InstrumentAny],
1705    instruments_by_symbol: &Arc<AtomicMap<Ustr, InstrumentAny>>,
1706) -> Vec<InstrumentAny> {
1707    fetched
1708        .iter()
1709        .filter(|instrument| {
1710            instruments_by_symbol
1711                .get_cloned(&instrument.symbol().inner())
1712                .is_none_or(|cached| !instrument_definitions_match(&cached, instrument))
1713        })
1714        .cloned()
1715        .collect()
1716}
1717
1718/// Updates the data client cache, HTTP client cache, and both WebSocket
1719/// caches, then bumps the update sequence. Callers serialize diff-update
1720/// sequences through the instrument update lock.
1721fn cache_instrument_updates(
1722    changed: &[InstrumentAny],
1723    instruments_by_symbol: &Arc<AtomicMap<Ustr, InstrumentAny>>,
1724    http_client: &OKXHttpClient,
1725    ws_public: Option<&OKXWebSocketClient>,
1726    ws_business: Option<&OKXWebSocketClient>,
1727    instrument_update_lock: &InstrumentUpdateLock,
1728) {
1729    if changed.is_empty() {
1730        return;
1731    }
1732
1733    instruments_by_symbol.rcu(|m| {
1734        for instrument in changed {
1735            m.insert(instrument.symbol().inner(), instrument.clone());
1736        }
1737    });
1738    http_client.cache_instruments(changed);
1739
1740    if let Some(ws) = ws_public {
1741        ws.cache_instruments(changed);
1742    }
1743
1744    if let Some(ws) = ws_business {
1745        ws.cache_instruments(changed);
1746    }
1747
1748    instrument_update_lock
1749        .write_seq
1750        .fetch_add(1, Ordering::SeqCst);
1751}
1752
1753/// Publishes new or changed definitions as [`DataEvent::Data`] after
1754/// updating every cache, so consumers never observe a definition the caches
1755/// do not yet hold. Callers serialize diff-update-publish sequences through
1756/// the instrument update lock.
1757fn publish_instrument_updates(
1758    changed: &[InstrumentAny],
1759    instruments_by_symbol: &Arc<AtomicMap<Ustr, InstrumentAny>>,
1760    http_client: &OKXHttpClient,
1761    ws_public: Option<&OKXWebSocketClient>,
1762    ws_business: Option<&OKXWebSocketClient>,
1763    instrument_update_lock: &InstrumentUpdateLock,
1764    data_sender: &EventSender<DataEvent>,
1765) {
1766    cache_instrument_updates(
1767        changed,
1768        instruments_by_symbol,
1769        http_client,
1770        ws_public,
1771        ws_business,
1772        instrument_update_lock,
1773    );
1774
1775    for instrument in changed {
1776        if let Err(e) = data_sender.send(DataEvent::Data(instrument.clone().into())) {
1777            log::error!("Failed to emit instrument event: {e}");
1778        }
1779    }
1780}
1781
1782fn contract_filter_with_config(config: &OKXDataClientConfig, instrument: &InstrumentAny) -> bool {
1783    contract_filter_with_config_types(config.contract_types.as_ref(), instrument)
1784}
1785
1786/// Returns `true` when a venue definition belongs to the configured scope:
1787/// the contract type filter, plus configured families for derivative types.
1788/// The instruments channel pushes the whole type, so updates outside the
1789/// configured families must not enter the cache or publish downstream.
1790fn definition_in_scope(
1791    config: &OKXDataClientConfig,
1792    okx_inst: &OKXInstrument,
1793    instrument: &InstrumentAny,
1794) -> bool {
1795    if !contract_filter_with_config(config, instrument) {
1796        return false;
1797    }
1798
1799    let Some(families) = &config.instrument_families else {
1800        return true;
1801    };
1802
1803    if families.is_empty()
1804        || !matches!(
1805            okx_inst.inst_type,
1806            OKXInstrumentType::Option
1807                | OKXInstrumentType::Futures
1808                | OKXInstrumentType::Swap
1809                | OKXInstrumentType::Events
1810        )
1811    {
1812        return true;
1813    }
1814
1815    let family_key = if matches!(okx_inst.inst_type, OKXInstrumentType::Events) {
1816        // Events carry their family as the series ID, matching the REST path
1817        // which passes configured families as series_id
1818        okx_inst.series_id.map(|series| series.as_str())
1819    } else {
1820        Some(okx_inst.inst_family.as_str())
1821    };
1822
1823    let Some(family_key) = family_key else {
1824        return false;
1825    };
1826
1827    families.iter().any(|family| family.as_str() == family_key)
1828}
1829
1830fn configured_instrument_types(config: &OKXDataClientConfig) -> Vec<OKXInstrumentType> {
1831    if config.instrument_types.is_empty() {
1832        vec![OKXInstrumentType::Spot]
1833    } else {
1834        config.instrument_types.clone()
1835    }
1836}
1837
1838/// Fetches every instrument covered by the configuration, applying the
1839/// contract type filter. Fails on the first type or family error; a spread
1840/// endpoint failure is logged and skipped because spread instruments are
1841/// supplemental. Does not touch any cache: a caller may discard a stale
1842/// snapshot, so cache updates happen only in guarded publish sections.
1843async fn fetch_configured_instruments(
1844    http_client: &OKXHttpClient,
1845    config: &OKXDataClientConfig,
1846) -> anyhow::Result<Vec<InstrumentAny>> {
1847    let instrument_types = configured_instrument_types(config);
1848    let mut all_instruments = Vec::new();
1849
1850    for inst_type in &instrument_types {
1851        let Some(families) = resolve_instrument_families(&config.instrument_families, *inst_type)
1852        else {
1853            continue;
1854        };
1855
1856        if families.is_empty() {
1857            let (mut fetched, _inst_id_codes) = http_client
1858                .request_instruments(*inst_type, None)
1859                .await
1860                .with_context(|| format!("failed to request OKX instruments for {inst_type:?}"))?;
1861
1862            fetched.retain(|instrument| contract_filter_with_config(config, instrument));
1863            all_instruments.extend(fetched);
1864        } else {
1865            for family in &families {
1866                let (mut fetched, _inst_id_codes) = http_client
1867                    .request_instruments(*inst_type, Some(family.clone()))
1868                    .await
1869                    .with_context(|| {
1870                        format!(
1871                            "failed to request OKX instruments for {inst_type:?} family {family}"
1872                        )
1873                    })?;
1874
1875                fetched.retain(|instrument| contract_filter_with_config(config, instrument));
1876                all_instruments.extend(fetched);
1877            }
1878        }
1879    }
1880
1881    if config.load_spreads {
1882        match http_client
1883            .request_spread_instruments(GetSpreadsParams {
1884                state: Some("live".to_string()),
1885                ..Default::default()
1886            })
1887            .await
1888        {
1889            Ok(mut fetched) => {
1890                fetched.retain(|instrument| contract_filter_with_config(config, instrument));
1891                all_instruments.extend(fetched);
1892            }
1893            Err(e) => {
1894                log::error!("Failed to fetch OKX spread instruments: {e:?}");
1895            }
1896        }
1897    }
1898
1899    Ok(all_instruments)
1900}
1901
1902/// Summary of a single instrument reconciliation pass.
1903#[derive(Debug)]
1904struct InstrumentReconciliation {
1905    fetched: usize,
1906    changed: usize,
1907    missing: usize,
1908}
1909
1910/// Reconciles the instrument cache against the REST API.
1911///
1912/// Fetches every configured instrument type and family, plus spread instruments
1913/// when `load_spreads` is set, then updates the data client, HTTP client, and
1914/// WebSocket caches with new or materially changed definitions before
1915/// publishing them as [`DataEvent::Data`]. Unchanged definitions are
1916/// not republished. Cached instruments missing from the response are retained
1917/// because they may still back open subscriptions; the instruments WebSocket
1918/// channel communicates state changes such as suspension or delisting.
1919async fn reconcile_instruments(
1920    http_client: &OKXHttpClient,
1921    config: &OKXDataClientConfig,
1922    instruments_by_symbol: &Arc<AtomicMap<Ustr, InstrumentAny>>,
1923    instrument_update_lock: &InstrumentUpdateLock,
1924    ws_public: Option<&OKXWebSocketClient>,
1925    ws_business: Option<&OKXWebSocketClient>,
1926    data_sender: &EventSender<DataEvent>,
1927) -> anyhow::Result<InstrumentReconciliation> {
1928    let seq_before = instrument_update_lock.write_seq.load(Ordering::SeqCst);
1929    let fetched = fetch_configured_instruments(http_client, config).await?;
1930
1931    // Hold the instrument lock from the diff through publication so a concurrent
1932    // instruments channel update cannot interleave with this pass
1933    let _update_guard = instrument_update_lock.mutex.lock();
1934
1935    // A write during the fetch means the snapshot is stale relative to the
1936    // instrument cache; skip publishing it and let the next pass reconcile fully
1937    let changed = if instrument_update_lock.write_seq.load(Ordering::SeqCst) == seq_before {
1938        changed_definitions(&fetched, instruments_by_symbol)
1939    } else {
1940        log::debug!("OKX instrument cache changed during refresh fetch, skipping publish");
1941        Vec::new()
1942    };
1943
1944    if !changed.is_empty() {
1945        publish_instrument_updates(
1946            &changed,
1947            instruments_by_symbol,
1948            http_client,
1949            ws_public,
1950            ws_business,
1951            instrument_update_lock,
1952            data_sender,
1953        );
1954    }
1955
1956    let fetched_symbols: AHashSet<Ustr> = fetched
1957        .iter()
1958        .map(|instrument| instrument.symbol().inner())
1959        .collect();
1960    let missing = instruments_by_symbol
1961        .load()
1962        .keys()
1963        .filter(|symbol| !fetched_symbols.contains(*symbol))
1964        .count();
1965
1966    if missing > 0 {
1967        log::debug!(
1968            "{missing} cached instruments absent from OKX REST response, retaining cached definitions"
1969        );
1970    }
1971
1972    Ok(InstrumentReconciliation {
1973        fetched: fetched.len(),
1974        changed: changed.len(),
1975        missing,
1976    })
1977}
1978
1979#[async_trait::async_trait(?Send)]
1980impl DataClient for OKXDataClient {
1981    fn client_id(&self) -> ClientId {
1982        self.client_id
1983    }
1984
1985    fn venue(&self) -> Option<Venue> {
1986        Some(self.venue())
1987    }
1988
1989    fn start(&mut self) -> anyhow::Result<()> {
1990        log::info!(
1991            "Started: client_id={}, vip_level={:?}, instrument_types={:?}, environment={}, proxy_url={:?}",
1992            self.client_id,
1993            self.vip_level(),
1994            self.config.instrument_types,
1995            self.config.environment,
1996            self.config.proxy_url,
1997        );
1998        Ok(())
1999    }
2000
2001    fn stop(&mut self) -> anyhow::Result<()> {
2002        log::info!("Stopping {id}", id = self.client_id);
2003        self.begin_generation_shutdown();
2004        Ok(())
2005    }
2006
2007    fn reset(&mut self) -> anyhow::Result<()> {
2008        log::debug!("Resetting {id}", id = self.client_id);
2009        self.begin_generation_shutdown();
2010        self.book_deltas.store(AHashSet::new());
2011        self.book_depths.store(AHashMap::new());
2012        self.book_channels.store(AHashMap::new());
2013        self.book_sync.clear();
2014        self.option_greeks_subs
2015            .store(AHashMap::<InstrumentId, AHashSet<OKXGreeksType>>::new());
2016        self.option_summary_family_subs.lock().clear();
2017        Ok(())
2018    }
2019
2020    fn dispose(&mut self) -> anyhow::Result<()> {
2021        log::debug!("Disposing {id}", id = self.client_id);
2022        self.begin_generation_shutdown();
2023        Ok(())
2024    }
2025
2026    async fn connect(&mut self) -> anyhow::Result<()> {
2027        if self.is_connected() && self.tasks.is_open() {
2028            return Ok(());
2029        }
2030
2031        let ws_public = self.ws_public.clone();
2032        let ws_business = self.ws_business.clone();
2033        let setup_guard = TaskGroupGuard::new(&[&self.tasks], move || {
2034            if let Some(ws) = ws_public {
2035                ws.begin_shutdown();
2036            }
2037
2038            if let Some(ws) = ws_business {
2039                ws.begin_shutdown();
2040            }
2041        });
2042
2043        if let Err(e) = self.connect_session().await {
2044            if let Err(teardown_error) = self.teardown_transports().await {
2045                return Err(e.context(format!(
2046                    "OKX data startup teardown failed: {teardown_error}"
2047                )));
2048            }
2049            return Err(e);
2050        }
2051
2052        self.is_connected.store(true, Ordering::Release);
2053        setup_guard.disarm();
2054        log::info!("Connected: client_id={}", self.client_id);
2055        Ok(())
2056    }
2057
2058    async fn disconnect(&mut self) -> anyhow::Result<()> {
2059        if self.is_disconnected()
2060            && !self.transports_started
2061            && self.tasks.is_empty()
2062            && self.ws_public.as_ref().is_none_or(|ws| !ws.has_task())
2063            && self.ws_business.as_ref().is_none_or(|ws| !ws.has_task())
2064        {
2065            return Ok(());
2066        }
2067
2068        if !self.is_disconnected() {
2069            if let Some(ref ws) = self.ws_public
2070                && let Err(e) = ws.unsubscribe_all().await
2071            {
2072                log::warn!("Failed to unsubscribe all from public websocket: {e:?}");
2073            }
2074
2075            if let Some(ref ws) = self.ws_business
2076                && let Err(e) = ws.unsubscribe_all().await
2077            {
2078                log::warn!("Failed to unsubscribe all from business websocket: {e:?}");
2079            }
2080
2081            // Allow time for unsubscribe confirmations
2082            time::sleep(Duration::from_millis(500)).await;
2083        }
2084
2085        self.begin_generation_shutdown();
2086        self.teardown_transports().await?;
2087        log::info!("Disconnected: client_id={}", self.client_id);
2088        Ok(())
2089    }
2090
2091    fn is_connected(&self) -> bool {
2092        self.is_connected.load(Ordering::Relaxed)
2093    }
2094
2095    fn is_disconnected(&self) -> bool {
2096        !self.is_connected()
2097    }
2098
2099    fn subscribe_instruments(&mut self, _cmd: SubscribeInstruments) -> anyhow::Result<()> {
2100        for inst_type in &self.config.instrument_types {
2101            let ws = self.public_ws()?.clone();
2102            let inst_type = *inst_type;
2103
2104            self.spawn_ws(
2105                async move {
2106                    ws.subscribe_instruments(inst_type)
2107                        .await
2108                        .context("instruments subscription")?;
2109                    Ok(())
2110                },
2111                "subscribe_instruments",
2112            );
2113        }
2114        Ok(())
2115    }
2116
2117    fn subscribe_instrument(&mut self, cmd: SubscribeInstrument) -> anyhow::Result<()> {
2118        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2119            // OKX instruments channel doesn't support subscribing to individual instruments via instId
2120            // Instead, subscribe to the instrument type if not already subscribed
2121            let ws = self.public_ws()?.clone();
2122            self.spawn_ws(
2123                async move {
2124                    ws.subscribe_instrument(instrument_id)
2125                        .await
2126                        .context("instrument type subscription")?;
2127                    Ok(())
2128                },
2129                "subscribe_instrument",
2130            );
2131
2132            Ok(())
2133        })
2134    }
2135
2136    fn subscribe_book_deltas(&mut self, cmd: SubscribeBookDeltas) -> anyhow::Result<()> {
2137        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2138            let cmd = cmd.with_instrument_ids(instrument_id);
2139            anyhow::ensure!(
2140                cmd.book_type == BookType::L2_MBP,
2141                "OKX only supports L2_MBP order books"
2142            );
2143            let channel = self.book_channel(instrument_id, cmd.depth, cmd.params.as_ref());
2144            let was_subscribed = self.book_deltas.contains(&instrument_id);
2145            self.book_deltas.insert(instrument_id);
2146
2147            if let Err(e) = self.subscribe_book_channel(instrument_id, channel) {
2148                if !was_subscribed {
2149                    self.book_deltas.remove(&instrument_id);
2150                }
2151
2152                return Err(e);
2153            }
2154
2155            Ok(())
2156        })
2157    }
2158
2159    fn subscribe_book_depth(&mut self, cmd: SubscribeBookDepth) -> anyhow::Result<()> {
2160        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2161            let cmd = cmd.with_instrument_ids(instrument_id);
2162            anyhow::ensure!(
2163                cmd.book_type == BookType::L2_MBP,
2164                "OKX only supports L2_MBP order books"
2165            );
2166            let depth = cmd
2167                .depth
2168                .map_or(BOOK_SNAPSHOT_DEPTH, std::num::NonZero::get);
2169            anyhow::ensure!(
2170                depth <= BOOK_SNAPSHOT_DEPTH,
2171                "OKX depth snapshots support at most {BOOK_SNAPSHOT_DEPTH} levels"
2172            );
2173            anyhow::ensure!(
2174                !cmd.params
2175                    .as_ref()
2176                    .and_then(|params| params.get_bool("rpi"))
2177                    .unwrap_or(false),
2178                "OKX native depth snapshots do not support RPI"
2179            );
2180
2181            if let Some(active) = self.book_depths.get_cloned(&instrument_id) {
2182                anyhow::ensure!(
2183                    active == depth,
2184                    "Conflicting OKX snapshot depth for {instrument_id}"
2185                );
2186                return Ok(());
2187            }
2188
2189            if self.http_client.is_spread(instrument_id) {
2190                self.book_depths.insert(instrument_id, depth);
2191                if let Err(e) =
2192                    self.subscribe_book_channel(instrument_id, OKXBookChannel::SprdBooks5)
2193                {
2194                    self.book_depths.remove(&instrument_id);
2195                    return Err(e);
2196                }
2197            } else {
2198                let ws = self.public_ws()?.clone();
2199                self.book_depths.insert(instrument_id, depth);
2200                self.spawn_ws(
2201                    async move {
2202                        ws.subscribe_book_depth5(instrument_id)
2203                            .await
2204                            .context("book depth subscription")
2205                    },
2206                    "book depth subscription",
2207                );
2208            }
2209
2210            Ok(())
2211        })
2212    }
2213
2214    fn subscribe_quotes(&mut self, cmd: SubscribeQuotes) -> anyhow::Result<()> {
2215        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2216            if self.http_client.is_spread(instrument_id) {
2217                let ws = self.business_ws()?.clone();
2218                self.spawn_ws(
2219                    async move {
2220                        ws.subscribe_spread_quotes(instrument_id)
2221                            .await
2222                            .context("spread quotes subscription")
2223                    },
2224                    "spread quote subscription",
2225                );
2226
2227                return Ok(());
2228            }
2229
2230            let ws = self.public_ws()?.clone();
2231            self.spawn_ws(
2232                async move {
2233                    ws.subscribe_quotes(instrument_id)
2234                        .await
2235                        .context("quotes subscription")
2236                },
2237                "quote subscription",
2238            );
2239
2240            Ok(())
2241        })
2242    }
2243
2244    fn subscribe_trades(&mut self, cmd: SubscribeTrades) -> anyhow::Result<()> {
2245        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2246            if self.http_client.is_spread(instrument_id) {
2247                let ws = self.business_ws()?.clone();
2248                self.spawn_ws(
2249                    async move {
2250                        ws.subscribe_spread_trades(instrument_id)
2251                            .await
2252                            .context("spread trades subscription")
2253                    },
2254                    "spread trade subscription",
2255                );
2256
2257                return Ok(());
2258            }
2259
2260            let ws = self.public_ws()?.clone();
2261            self.spawn_ws(
2262                async move {
2263                    ws.subscribe_trades(instrument_id, false)
2264                        .await
2265                        .context("trades subscription")
2266                },
2267                "trade subscription",
2268            );
2269
2270            Ok(())
2271        })
2272    }
2273
2274    fn subscribe_mark_prices(&mut self, cmd: SubscribeMarkPrices) -> anyhow::Result<()> {
2275        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2276            let ws = self.public_ws()?.clone();
2277            self.spawn_ws(
2278                async move {
2279                    ws.subscribe_mark_prices(instrument_id)
2280                        .await
2281                        .context("mark price subscription")
2282                },
2283                "mark price subscription",
2284            );
2285
2286            Ok(())
2287        })
2288    }
2289
2290    fn subscribe_index_prices(&mut self, cmd: SubscribeIndexPrices) -> anyhow::Result<()> {
2291        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2292            let ws = self.public_ws()?.clone();
2293            let symbol = instrument_id.symbol.inner();
2294
2295            let (base, quote) = parse_base_quote_from_symbol(symbol.as_str())?;
2296            let base_pair = Ustr::from(&format!("{base}-{quote}"));
2297            self.index_ticker_map.rcu(|m| {
2298                m.entry(base_pair).or_default().insert(symbol);
2299            });
2300
2301            self.spawn_ws(
2302                async move {
2303                    ws.subscribe_index_prices(instrument_id)
2304                        .await
2305                        .context("index price subscription")
2306                },
2307                "index price subscription",
2308            );
2309
2310            Ok(())
2311        })
2312    }
2313
2314    fn subscribe_bars(&mut self, cmd: SubscribeBars) -> anyhow::Result<()> {
2315        execute_bar_subscriptions(&cmd.bar_types, |bar_type| {
2316            let ws = self.business_ws()?.clone();
2317            self.spawn_ws(
2318                async move {
2319                    ws.subscribe_bars(bar_type)
2320                        .await
2321                        .context("bars subscription")
2322                },
2323                "bar subscription",
2324            );
2325
2326            Ok(())
2327        })
2328    }
2329
2330    fn subscribe_funding_rates(&mut self, cmd: SubscribeFundingRates) -> anyhow::Result<()> {
2331        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2332            let ws = self.public_ws()?.clone();
2333            self.spawn_ws(
2334                async move {
2335                    ws.subscribe_funding_rates(instrument_id)
2336                        .await
2337                        .context("funding rate subscription")
2338                },
2339                "funding rate subscription",
2340            );
2341
2342            Ok(())
2343        })
2344    }
2345
2346    fn subscribe_option_greeks(&mut self, cmd: SubscribeOptionGreeks) -> anyhow::Result<()> {
2347        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2348            let cmd = cmd.with_instrument_ids(instrument_id);
2349            let conventions = parse_greeks_conventions_from_params(cmd.params.as_ref());
2350            self.option_greeks_subs.insert(instrument_id, conventions);
2351
2352            let family = extract_inst_family(instrument_id.symbol.inner().as_str())?;
2353
2354            let is_first = {
2355                let mut family_subs = self.option_summary_family_subs.lock();
2356                let count = family_subs.entry(family).or_default();
2357                *count += 1;
2358                *count == 1
2359            };
2360
2361            if is_first {
2362                let ws = self.public_ws()?.clone();
2363                let family_subs = self.option_summary_family_subs.clone();
2364                self.spawn_ws(
2365                    async move {
2366                        let result = ws
2367                            .subscribe_option_summary(family)
2368                            .await
2369                            .context("opt-summary subscription");
2370
2371                        if result.is_err() {
2372                            // Roll back the refcount so a retry can re-arm the subscribe;
2373                            // otherwise the family wedges and Greeks stay dark.
2374                            let mut subs = family_subs.lock();
2375
2376                            if let Some(count) = subs.get_mut(&family) {
2377                                *count = count.saturating_sub(1);
2378                                if *count == 0 {
2379                                    subs.remove(&family);
2380                                }
2381                            }
2382                        }
2383
2384                        result
2385                    },
2386                    "option greeks subscription",
2387                );
2388            }
2389
2390            Ok(())
2391        })
2392    }
2393
2394    fn subscribe_instrument_status(
2395        &mut self,
2396        cmd: SubscribeInstrumentStatus,
2397    ) -> anyhow::Result<()> {
2398        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2399            let ws = self.public_ws()?.clone();
2400            self.spawn_ws(
2401                async move {
2402                    ws.subscribe_instrument(instrument_id)
2403                        .await
2404                        .context("instrument status subscription")
2405                },
2406                "instrument status subscription",
2407            );
2408
2409            Ok(())
2410        })
2411    }
2412
2413    fn unsubscribe_instrument(&mut self, cmd: &UnsubscribeInstrument) -> anyhow::Result<()> {
2414        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2415            let ws = self.public_ws()?.clone();
2416            self.spawn_ws(
2417                async move {
2418                    ws.unsubscribe_instrument(instrument_id)
2419                        .await
2420                        .context("instrument unsubscribe")?;
2421                    Ok(())
2422                },
2423                "unsubscribe_instrument",
2424            );
2425
2426            Ok(())
2427        })
2428    }
2429
2430    fn unsubscribe_book_deltas(&mut self, cmd: &UnsubscribeBookDeltas) -> anyhow::Result<()> {
2431        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2432            if !self.book_deltas.contains(&instrument_id) {
2433                return Ok(());
2434            }
2435
2436            if !self.http_client.is_spread(instrument_id)
2437                || !self.book_depths.contains_key(&instrument_id)
2438            {
2439                self.unsubscribe_book_channel(instrument_id)?;
2440            }
2441
2442            self.book_deltas.remove(&instrument_id);
2443            Ok(())
2444        })
2445    }
2446
2447    fn unsubscribe_book_depth(&mut self, cmd: &UnsubscribeBookDepth) -> anyhow::Result<()> {
2448        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2449            if !self.book_depths.contains_key(&instrument_id) {
2450                return Ok(());
2451            }
2452
2453            if self.http_client.is_spread(instrument_id) {
2454                if !self.book_deltas.contains(&instrument_id) {
2455                    self.unsubscribe_book_channel(instrument_id)?;
2456                }
2457            } else {
2458                let ws = self.public_ws()?.clone();
2459                self.spawn_ws(
2460                    async move {
2461                        ws.unsubscribe_book_depth5(instrument_id)
2462                            .await
2463                            .context("book depth unsubscribe")
2464                    },
2465                    "book depth unsubscribe",
2466                );
2467            }
2468
2469            self.book_depths.remove(&instrument_id);
2470            Ok(())
2471        })
2472    }
2473
2474    fn unsubscribe_quotes(&mut self, cmd: &UnsubscribeQuotes) -> anyhow::Result<()> {
2475        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2476            if self.http_client.is_spread(instrument_id) {
2477                let ws = self.business_ws()?.clone();
2478                self.spawn_ws(
2479                    async move {
2480                        ws.unsubscribe_spread_quotes(instrument_id)
2481                            .await
2482                            .context("spread quotes unsubscribe")
2483                    },
2484                    "spread quote unsubscribe",
2485                );
2486
2487                return Ok(());
2488            }
2489
2490            let ws = self.public_ws()?.clone();
2491            self.spawn_ws(
2492                async move {
2493                    ws.unsubscribe_quotes(instrument_id)
2494                        .await
2495                        .context("quotes unsubscribe")
2496                },
2497                "quote unsubscribe",
2498            );
2499
2500            Ok(())
2501        })
2502    }
2503
2504    fn unsubscribe_trades(&mut self, cmd: &UnsubscribeTrades) -> anyhow::Result<()> {
2505        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2506            if self.http_client.is_spread(instrument_id) {
2507                let ws = self.business_ws()?.clone();
2508                self.spawn_ws(
2509                    async move {
2510                        ws.unsubscribe_spread_trades(instrument_id)
2511                            .await
2512                            .context("spread trades unsubscribe")
2513                    },
2514                    "spread trade unsubscribe",
2515                );
2516
2517                return Ok(());
2518            }
2519
2520            let ws = self.public_ws()?.clone();
2521            self.spawn_ws(
2522                async move {
2523                    ws.unsubscribe_trades(instrument_id, false) // TODO: Aggregated trades?
2524                        .await
2525                        .context("trades unsubscribe")
2526                },
2527                "trade unsubscribe",
2528            );
2529
2530            Ok(())
2531        })
2532    }
2533
2534    fn unsubscribe_mark_prices(&mut self, cmd: &UnsubscribeMarkPrices) -> anyhow::Result<()> {
2535        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2536            let ws = self.public_ws()?.clone();
2537            self.spawn_ws(
2538                async move {
2539                    ws.unsubscribe_mark_prices(instrument_id)
2540                        .await
2541                        .context("mark price unsubscribe")
2542                },
2543                "mark price unsubscribe",
2544            );
2545
2546            Ok(())
2547        })
2548    }
2549
2550    fn unsubscribe_index_prices(&mut self, cmd: &UnsubscribeIndexPrices) -> anyhow::Result<()> {
2551        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2552            let ws = self.public_ws()?.clone();
2553            let symbol = instrument_id.symbol.inner();
2554
2555            // The OKX index-tickers channel is keyed by base pair, so multiple
2556            // instruments on the same pair share one subscription. Per-base-pair
2557            // refcounting lives on the WS client, so we always forward the
2558            // unsubscribe and let the WS layer fire the venue request only when
2559            // it knows the last subscriber dropped. Local routing in
2560            // `index_ticker_map` is still maintained for downstream emit fan-out.
2561            if let Ok((base, quote)) = parse_base_quote_from_symbol(symbol.as_str()) {
2562                let base_pair = Ustr::from(&format!("{base}-{quote}"));
2563                self.index_ticker_map.rcu(|m| {
2564                    if let Some(set) = m.get_mut(&base_pair) {
2565                        set.remove(&symbol);
2566                        if set.is_empty() {
2567                            m.remove(&base_pair);
2568                        }
2569                    }
2570                });
2571            }
2572
2573            self.spawn_ws(
2574                async move {
2575                    ws.unsubscribe_index_prices(instrument_id)
2576                        .await
2577                        .context("index price unsubscribe")
2578                },
2579                "index price unsubscribe",
2580            );
2581
2582            Ok(())
2583        })
2584    }
2585
2586    fn unsubscribe_bars(&mut self, cmd: &UnsubscribeBars) -> anyhow::Result<()> {
2587        execute_bar_subscriptions(&cmd.bar_types, |bar_type| {
2588            let ws = self.business_ws()?.clone();
2589            self.spawn_ws(
2590                async move {
2591                    ws.unsubscribe_bars(bar_type)
2592                        .await
2593                        .context("bars unsubscribe")
2594                },
2595                "bar unsubscribe",
2596            );
2597
2598            Ok(())
2599        })
2600    }
2601
2602    fn unsubscribe_funding_rates(&mut self, cmd: &UnsubscribeFundingRates) -> anyhow::Result<()> {
2603        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2604            let ws = self.public_ws()?.clone();
2605            self.spawn_ws(
2606                async move {
2607                    ws.unsubscribe_funding_rates(instrument_id)
2608                        .await
2609                        .context("funding rate unsubscribe")
2610                },
2611                "funding rate unsubscribe",
2612            );
2613
2614            Ok(())
2615        })
2616    }
2617
2618    fn unsubscribe_option_greeks(&mut self, cmd: &UnsubscribeOptionGreeks) -> anyhow::Result<()> {
2619        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2620            self.option_greeks_subs.remove(&instrument_id);
2621
2622            let family = extract_inst_family(instrument_id.symbol.inner().as_str())?;
2623
2624            let should_unsubscribe = {
2625                let mut family_subs = self.option_summary_family_subs.lock();
2626
2627                if let Some(count) = family_subs.get_mut(&family) {
2628                    *count = count.saturating_sub(1);
2629                    if *count == 0 {
2630                        family_subs.remove(&family);
2631                        true
2632                    } else {
2633                        false
2634                    }
2635                } else {
2636                    false
2637                }
2638            };
2639
2640            if should_unsubscribe {
2641                let ws = self.public_ws()?.clone();
2642                self.spawn_ws(
2643                    async move {
2644                        ws.unsubscribe_option_summary(family)
2645                            .await
2646                            .context("opt-summary unsubscription")
2647                    },
2648                    "option greeks unsubscription",
2649                );
2650            }
2651
2652            Ok(())
2653        })
2654    }
2655
2656    fn unsubscribe_instrument_status(
2657        &mut self,
2658        cmd: &UnsubscribeInstrumentStatus,
2659    ) -> anyhow::Result<()> {
2660        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
2661            let ws = self.public_ws()?.clone();
2662            self.spawn_ws(
2663                async move {
2664                    ws.unsubscribe_instrument(instrument_id)
2665                        .await
2666                        .context("instrument status unsubscription")
2667                },
2668                "instrument status unsubscription",
2669            );
2670
2671            Ok(())
2672        })
2673    }
2674
2675    fn request_instruments(&self, request: RequestInstruments) -> anyhow::Result<()> {
2676        let http = self.http_client.clone();
2677        let sender = self.data_sender.clone();
2678        let instruments_cache = self.instruments_by_symbol.clone();
2679        let update_lock = self.instrument_update_lock.clone();
2680        let ws_public = self.ws_public.clone();
2681        let ws_business = self.ws_business.clone();
2682        let request_id = request.request_id;
2683        let client_id = request.client_id.unwrap_or(self.client_id);
2684        let venue = self.venue();
2685        let start = request.start;
2686        let end = request.end;
2687        let params = request.params;
2688        let clock = self.clock;
2689        let start_nanos = datetime_to_unix_nanos(start);
2690        let end_nanos = datetime_to_unix_nanos(end);
2691        let instrument_types = configured_instrument_types(&self.config);
2692        let contract_types = self.config.contract_types.clone();
2693        let instrument_families = self.config.instrument_families.clone();
2694        let load_spreads = self.config.load_spreads;
2695
2696        self.spawn_task(async move {
2697            let seq_before = update_lock.write_seq.load(Ordering::SeqCst);
2698            let mut all_instruments = Vec::new();
2699            let mut failures = Vec::new();
2700
2701            for inst_type in instrument_types {
2702                let Some(families) = resolve_instrument_families(&instrument_families, inst_type)
2703                else {
2704                    continue;
2705                };
2706
2707                if families.is_empty() {
2708                    match http
2709                        .request_instruments_with_parse_failures(inst_type, None)
2710                        .await
2711                    {
2712                        Ok((instruments, _inst_id_codes, parse_failures)) => {
2713                            failures.extend(parse_failures);
2714
2715                            for instrument in instruments {
2716                                if !contract_filter_with_config_types(
2717                                    contract_types.as_ref(),
2718                                    &instrument,
2719                                ) {
2720                                    continue;
2721                                }
2722
2723                                all_instruments.push(instrument);
2724                            }
2725                        }
2726                        Err(e) => {
2727                            failures.push(format!(
2728                                "Failed to fetch instruments for {inst_type:?}: {e:#}"
2729                            ));
2730                        }
2731                    }
2732                } else {
2733                    for family in families {
2734                        match http
2735                            .request_instruments_with_parse_failures(
2736                                inst_type,
2737                                Some(family.clone()),
2738                            )
2739                            .await
2740                        {
2741                            Ok((instruments, _inst_id_codes, parse_failures)) => {
2742                                failures.extend(parse_failures);
2743
2744                                for instrument in instruments {
2745                                    if !contract_filter_with_config_types(
2746                                        contract_types.as_ref(),
2747                                        &instrument,
2748                                    ) {
2749                                        continue;
2750                                    }
2751
2752                                    all_instruments.push(instrument);
2753                                }
2754                            }
2755                            Err(e) => {
2756                                failures.push(format!(
2757                                    "Failed to fetch instruments for {inst_type:?} family {family}: {e:#}"
2758                                ));
2759                            }
2760                        }
2761                    }
2762                }
2763            }
2764
2765            if load_spreads {
2766                match http
2767                    .request_spread_instruments_with_parse_failures(GetSpreadsParams {
2768                        state: Some("live".to_string()),
2769                        ..Default::default()
2770                    })
2771                    .await
2772                {
2773                    Ok((instruments, parse_failures)) => {
2774                        failures.extend(parse_failures);
2775
2776                        for instrument in instruments {
2777                            if !contract_filter_with_config_types(
2778                                contract_types.as_ref(),
2779                                &instrument,
2780                            ) {
2781                                continue;
2782                            }
2783
2784                            all_instruments.push(instrument);
2785                        }
2786                    }
2787                    Err(e) => {
2788                        failures.push(format!("Failed to fetch OKX spread instruments: {e:#}"));
2789                    }
2790                }
2791            }
2792
2793            {
2794                let _update_guard = update_lock
2795                    .mutex
2796                    .lock();
2797
2798                if update_lock.write_seq.load(Ordering::SeqCst) == seq_before {
2799                    cache_instrument_updates(
2800                        &all_instruments,
2801                        &instruments_cache,
2802                        &http,
2803                        ws_public.as_ref(),
2804                        ws_business.as_ref(),
2805                        &update_lock,
2806                    );
2807                } else {
2808                    log::debug!(
2809                        "OKX instrument cache changed during request fetch, skipping cache update"
2810                    );
2811                }
2812            }
2813
2814            let response = DataResponse::Instruments(InstrumentsResponse::new(
2815                request_id,
2816                client_id,
2817                venue,
2818                all_instruments,
2819                start_nanos,
2820                end_nanos,
2821                clock.get_time_ns(),
2822                params,
2823            ));
2824
2825            let event = if failures.is_empty() {
2826                completed_response(response)
2827            } else {
2828                DataEvent::RequestFailed(DataRequestFailed {
2829                    request_id,
2830                    reason: failures.join("; "),
2831                    response: Some(response),
2832                })
2833            };
2834
2835            if let Err(e) = sender.send(event) {
2836                log::error!("Failed to send instruments response: {e}");
2837            }
2838        });
2839
2840        Ok(())
2841    }
2842
2843    fn request_instrument(&self, request: RequestInstrument) -> anyhow::Result<()> {
2844        let instrument_id = request.single_instrument_id()?;
2845
2846        let http = self.http_client.clone();
2847        let sender = self.data_sender.clone();
2848        let instruments = self.instruments_by_symbol.clone();
2849        let update_lock = self.instrument_update_lock.clone();
2850        let ws_public = self.ws_public.clone();
2851        let ws_business = self.ws_business.clone();
2852        let request_id = request.request_id;
2853        let client_id = request.client_id.unwrap_or(self.client_id);
2854        let start = request.start;
2855        let end = request.end;
2856        let params = request.params;
2857        let clock = self.clock;
2858        let start_nanos = datetime_to_unix_nanos(start);
2859        let end_nanos = datetime_to_unix_nanos(end);
2860        let instrument_types = configured_instrument_types(&self.config);
2861        let contract_types = self.config.contract_types.clone();
2862        let load_spreads = self.config.load_spreads;
2863
2864        self.spawn_task(async move {
2865            let seq_before = update_lock.write_seq.load(Ordering::SeqCst);
2866
2867            let instrument = match http
2868                .request_instrument(instrument_id)
2869                .await
2870                .context("fetch instrument from API")
2871            {
2872                Ok(instrument) => instrument,
2873                Err(e) => {
2874                    if e.downcast_ref::<OKXInstrumentDefinitionError>().is_some() {
2875                        log::warn!("Instrument request skipped: {e:?}");
2876                    } else {
2877                        log::error!("Instrument request failed: {e:?}");
2878                    }
2879
2880                    if let Err(e) = sender.send(request_failure(request_id, &e)) {
2881                        log::error!("Failed to send instrument request failure: {e}");
2882                    }
2883
2884                    return;
2885                }
2886            };
2887
2888            let inst_id = instrument.id();
2889            let symbol = inst_id.symbol.as_str();
2890
2891            if instrument.is_spread() && !load_spreads {
2892                log::error!("Instrument {instrument_id} is a spread but load_spreads is false");
2893                return;
2894            }
2895
2896            if !instrument.is_spread() {
2897                let inst_type = okx_instrument_type_from_symbol(symbol);
2898                if !instrument_types.contains(&inst_type) {
2899                    log::error!(
2900                        "Instrument {instrument_id} type {inst_type:?} not in configured types {instrument_types:?}"
2901                    );
2902                    return;
2903                }
2904            }
2905
2906            if !contract_filter_with_config_types(contract_types.as_ref(), &instrument) {
2907                log::error!(
2908                    "Instrument {instrument_id} filtered out by contract_types config"
2909                );
2910                return;
2911            }
2912
2913            {
2914                let _update_guard = update_lock
2915                    .mutex
2916                    .lock();
2917
2918                if update_lock.write_seq.load(Ordering::SeqCst) == seq_before {
2919                    cache_instrument_updates(
2920                        std::slice::from_ref(&instrument),
2921                        &instruments,
2922                        &http,
2923                        ws_public.as_ref(),
2924                        ws_business.as_ref(),
2925                        &update_lock,
2926                    );
2927                } else {
2928                    log::debug!(
2929                        "OKX instrument cache changed during request fetch, skipping cache update"
2930                    );
2931                }
2932            }
2933
2934            let response = DataResponse::Instrument(Box::new(InstrumentResponse::new(
2935                request_id,
2936                client_id,
2937                instrument.id(),
2938                instrument,
2939                start_nanos,
2940                end_nanos,
2941                clock.get_time_ns(),
2942                params,
2943            )));
2944
2945            if let Err(e) = sender.send(completed_response(response)) {
2946                log::error!("Failed to send instrument response: {e}");
2947            }
2948        });
2949
2950        Ok(())
2951    }
2952
2953    fn request_book_snapshot(&self, request: RequestBookSnapshot) -> anyhow::Result<()> {
2954        let instrument_id = request.single_instrument_id()?;
2955
2956        let http = self.http_client.clone();
2957        let sender = self.data_sender.clone();
2958        let depth = request.depth.map(|n| n.get() as u32);
2959        let request_id = request.request_id;
2960        let client_id = request.client_id.unwrap_or(self.client_id);
2961        let params = request.params;
2962        let rpi = params
2963            .as_ref()
2964            .and_then(|params| params.get_bool("rpi"))
2965            .unwrap_or(false);
2966        let clock = self.clock;
2967
2968        self.spawn_task(async move {
2969            let result = if rpi {
2970                http.request_rpi_book_snapshot(instrument_id, depth).await
2971            } else {
2972                http.request_book_snapshot(instrument_id, depth).await
2973            };
2974
2975            match result.context("failed to request book snapshot from OKX") {
2976                Ok(book) => {
2977                    let response = DataResponse::Book(BookResponse::new(
2978                        request_id,
2979                        client_id,
2980                        instrument_id,
2981                        book,
2982                        None,
2983                        None,
2984                        clock.get_time_ns(),
2985                        params,
2986                    ));
2987
2988                    if let Err(e) = sender.send(DataEvent::Response(response)) {
2989                        log::error!("Failed to send book snapshot response: {e}");
2990                    }
2991                }
2992                Err(e) => {
2993                    log::error!("Book snapshot request failed: {e:?}");
2994
2995                    if let Err(e) = sender.send(request_failure(request_id, &e)) {
2996                        log::error!("Failed to send book snapshot request failure: {e}");
2997                    }
2998                }
2999            }
3000        });
3001
3002        Ok(())
3003    }
3004
3005    fn request_trades(&self, request: RequestTrades) -> anyhow::Result<()> {
3006        let instrument_id = request.single_instrument_id()?;
3007
3008        let http = self.http_client.clone();
3009        let sender = self.data_sender.clone();
3010        let start = request.start;
3011        let end = request.end;
3012        let limit = request.limit.map(|n| n.get() as u32);
3013        let request_id = request.request_id;
3014        let client_id = request.client_id.unwrap_or(self.client_id);
3015        let params = request.params;
3016        let clock = self.clock;
3017        let start_nanos = datetime_to_unix_nanos(start);
3018        let end_nanos = datetime_to_unix_nanos(end);
3019
3020        self.spawn_task(async move {
3021            match http
3022                .request_trades_with_coverage(instrument_id, start, end, limit)
3023                .await
3024                .context("failed to request trades from OKX")
3025            {
3026                Ok((trades, coverage)) => {
3027                    let response = DataResponse::Trades(TradesResponse::new(
3028                        request_id,
3029                        client_id,
3030                        instrument_id,
3031                        trades,
3032                        start_nanos,
3033                        end_nanos,
3034                        clock.get_time_ns(),
3035                        params,
3036                    ));
3037
3038                    if let Err(e) = sender.send(history_event(request_id, response, coverage)) {
3039                        log::error!("Failed to send trades response: {e}");
3040                    }
3041                }
3042                Err(e) => {
3043                    log::error!("Trade request failed: {e:?}");
3044
3045                    if let Err(e) = sender.send(request_failure(request_id, &e)) {
3046                        log::error!("Failed to send trades request failure: {e}");
3047                    }
3048                }
3049            }
3050        });
3051
3052        Ok(())
3053    }
3054
3055    fn request_bars(&self, request: RequestBars) -> anyhow::Result<()> {
3056        let bar_type = request.single_bar_type()?;
3057
3058        let http = self.http_client.clone();
3059        let sender = self.data_sender.clone();
3060        let start = request.start;
3061        let end = request.end;
3062        let limit = request.limit.map(|n| n.get() as u32);
3063        let request_id = request.request_id;
3064        let client_id = request.client_id.unwrap_or(self.client_id);
3065        let params = request.params;
3066        let clock = self.clock;
3067        let start_nanos = datetime_to_unix_nanos(start);
3068        let end_nanos = datetime_to_unix_nanos(end);
3069
3070        self.spawn_task(async move {
3071            match http
3072                .request_bars_with_coverage(bar_type, start, end, limit)
3073                .await
3074                .context("failed to request bars from OKX")
3075            {
3076                Ok((bars, coverage)) => {
3077                    let response = DataResponse::Bars(BarsResponse::new(
3078                        request_id,
3079                        client_id,
3080                        bar_type,
3081                        bars,
3082                        start_nanos,
3083                        end_nanos,
3084                        clock.get_time_ns(),
3085                        params,
3086                    ));
3087
3088                    if let Err(e) = sender.send(history_event(request_id, response, coverage)) {
3089                        log::error!("Failed to send bars response: {e}");
3090                    }
3091                }
3092                Err(e) => {
3093                    log::error!("Bar request failed: {e:?}");
3094
3095                    if let Err(e) = sender.send(request_failure(request_id, &e)) {
3096                        log::error!("Failed to send bars request failure: {e}");
3097                    }
3098                }
3099            }
3100        });
3101
3102        Ok(())
3103    }
3104
3105    fn request_funding_rates(&self, request: RequestFundingRates) -> anyhow::Result<()> {
3106        let instrument_id = request.single_instrument_id()?;
3107
3108        let http = self.http_client.clone();
3109        let sender = self.data_sender.clone();
3110        let start = request.start;
3111        let end = request.end;
3112        let limit = request.limit.map(|n| n.get() as u32);
3113        let request_id = request.request_id;
3114        let client_id = request.client_id.unwrap_or(self.client_id);
3115        let params = request.params;
3116        let clock = self.clock;
3117        let start_nanos = datetime_to_unix_nanos(start);
3118        let end_nanos = datetime_to_unix_nanos(end);
3119
3120        self.spawn_task(async move {
3121            match http
3122                .request_funding_rates_with_coverage(instrument_id, start, end, limit)
3123                .await
3124                .context("failed to request funding rates from OKX")
3125            {
3126                Ok((funding_rates, coverage)) => {
3127                    let response = DataResponse::FundingRates(FundingRatesResponse::new(
3128                        request_id,
3129                        client_id,
3130                        instrument_id,
3131                        funding_rates,
3132                        start_nanos,
3133                        end_nanos,
3134                        clock.get_time_ns(),
3135                        params,
3136                    ));
3137
3138                    if let Err(e) = sender.send(history_event(request_id, response, coverage)) {
3139                        log::error!("Failed to send funding rates response: {e}");
3140                    }
3141                }
3142                Err(e) => {
3143                    log::error!("Funding rates request failed: {e:?}");
3144
3145                    if let Err(e) = sender.send(request_failure(request_id, &e)) {
3146                        log::error!("Failed to send funding rates request failure: {e}");
3147                    }
3148                }
3149            }
3150        });
3151
3152        Ok(())
3153    }
3154
3155    fn request_option_chain_reference_price(
3156        &self,
3157        request: RequestOptionChainReferencePrice,
3158    ) -> anyhow::Result<()> {
3159        let http = self.http_client.clone();
3160        let sender = self.data_sender.clone();
3161        let series_id = request.series_id;
3162        let instrument_id = request.instrument_id;
3163        let request_id = request.request_id;
3164        let client_id = request.client_id.unwrap_or(self.client_id);
3165        let params = request.params;
3166        let clock = self.clock;
3167
3168        self.spawn_task(async move {
3169            let price = match http
3170                .request_option_chain_reference_price(instrument_id)
3171                .await
3172                .context("failed to request option-chain reference price from OKX")
3173            {
3174                Ok(price) => price,
3175                Err(e) => {
3176                    log::error!(
3177                        "Option-chain reference price request failed for {series_id}: {e:?}"
3178                    );
3179                    None
3180                }
3181            };
3182            let response =
3183                DataResponse::OptionChainReferencePrice(OptionChainReferencePriceResponse::new(
3184                    request_id,
3185                    client_id,
3186                    series_id,
3187                    price,
3188                    clock.get_time_ns(),
3189                    params,
3190                ));
3191
3192            if let Err(e) = sender.send(DataEvent::Response(response)) {
3193                log::error!("Failed to send option-chain reference price response: {e}");
3194            }
3195        });
3196
3197        Ok(())
3198    }
3199}
3200
3201/// Resolves the set of [`OKXGreeksType`] conventions for an option greeks subscription.
3202///
3203/// Reads the `greeks_convention` key from `params`, accepting either a single
3204/// [`GreeksConvention`] string (e.g. `"BLACK_SCHOLES"` or `"PRICE_ADJUSTED"`) or a
3205/// JSON array of such strings. Unrecognized entries log a warning and are skipped.
3206/// Returns the default set `{Bs, Pa}` when the key is absent, unparsable, or
3207/// yields no valid entries so every subscription defaults to both conventions.
3208pub(crate) fn parse_greeks_conventions_from_params(
3209    params: Option<&Params>,
3210) -> AHashSet<OKXGreeksType> {
3211    let default_set: AHashSet<OKXGreeksType> =
3212        [OKXGreeksType::Bs, OKXGreeksType::Pa].into_iter().collect();
3213
3214    let Some(value) = params.and_then(|p| p.get("greeks_convention")) else {
3215        return default_set;
3216    };
3217
3218    let mut out = AHashSet::new();
3219    match value {
3220        serde_json::Value::String(s) => push_convention_str(&mut out, s),
3221        serde_json::Value::Array(items) => {
3222            for item in items {
3223                if let Some(s) = item.as_str() {
3224                    push_convention_str(&mut out, s);
3225                } else {
3226                    log::warn!("Ignoring non-string greeks_convention entry {item:?}");
3227                }
3228            }
3229        }
3230        other => {
3231            log::warn!(
3232                "Unsupported greeks_convention value {other:?}, defaulting to both conventions"
3233            );
3234        }
3235    }
3236
3237    if out.is_empty() { default_set } else { out }
3238}
3239
3240fn push_convention_str(out: &mut AHashSet<OKXGreeksType>, raw: &str) {
3241    match raw.parse::<GreeksConvention>() {
3242        Ok(convention) => {
3243            out.insert(convention.into());
3244        }
3245        Err(_) => log::warn!("Unrecognized greeks_convention {raw:?}, skipping"),
3246    }
3247}
3248
3249#[cfg(test)]
3250mod tests {
3251    use std::{collections::HashMap, net::SocketAddr, sync::Arc};
3252
3253    use axum::{Router, extract::Query, response::Json, routing::get};
3254    use nautilus_common::{
3255        config::ConfigError, live::runner::replace_data_event_sender, testing::wait_until_async,
3256    };
3257    use nautilus_core::UUID4;
3258    use nautilus_model::{
3259        identifiers::Symbol,
3260        instruments::{
3261            CryptoFuture, CurrencyPair,
3262            stubs::{crypto_future_btcusdt, currency_pair_btcusdt},
3263        },
3264        types::{Price, Quantity},
3265    };
3266    use nautilus_network::websocket::TransportBackend;
3267    use rstest::rstest;
3268    use serde_json::{Value, json};
3269
3270    use super::*;
3271    use crate::{
3272        common::{
3273            consts::OKX_CLIENT_ID,
3274            enums::{OKXContractType, OKXEnvironment},
3275            models::OKXInstrument,
3276            testing::load_test_json,
3277        },
3278        websocket::{enums::OKXWsChannel, messages::OKXWsFrame},
3279    };
3280
3281    #[rstest]
3282    #[case(None, None)]
3283    #[case(Some(OKXVipLevel::Vip4), Some("vip-key"))]
3284    fn vip_public_socket_receives_credentials(
3285        #[case] vip_level: Option<OKXVipLevel>,
3286        #[case] expected_key: Option<&str>,
3287    ) {
3288        let (sender, _receiver) = tokio::sync::mpsc::unbounded_channel();
3289        replace_data_event_sender(sender);
3290
3291        let config = OKXDataClientConfig {
3292            api_key: Some("vip-key".into()),
3293            api_secret: Some("vip-secret".into()),
3294            api_passphrase: Some("vip-passphrase".into()),
3295            vip_level,
3296            ..Default::default()
3297        };
3298
3299        let client = OKXDataClient::new(*OKX_CLIENT_ID, config).unwrap();
3300        assert_eq!(client.public_ws().unwrap().api_key(), expected_key);
3301        assert_eq!(client.business_ws().unwrap().api_key(), None);
3302    }
3303
3304    #[rstest]
3305    fn vip_public_socket_rejects_empty_credentials() {
3306        let config = OKXDataClientConfig {
3307            api_key: Some(" ".into()),
3308            api_secret: Some("vip-secret".into()),
3309            api_passphrase: Some("vip-passphrase".into()),
3310            vip_level: Some(OKXVipLevel::Vip4),
3311            ..Default::default()
3312        };
3313
3314        assert_eq!(
3315            config.validate(),
3316            Err(ConfigError::dependency(
3317                "vip_level",
3318                "api_key, api_secret, api_passphrase",
3319                "VIP book channels require authentication"
3320            ))
3321        );
3322    }
3323
3324    #[rstest]
3325    #[case("BTC-USD_UM_XPERP-310404.OKX")]
3326    #[case("BTC-USD_UM-261030.OKX")]
3327    fn usd_margined_futures_use_regular_book_channel(
3328        mut crypto_future_btcusdt: CryptoFuture,
3329        #[case] instrument_id: &str,
3330        #[values(false, true)] cached: bool,
3331    ) {
3332        let (sender, _receiver) = tokio::sync::mpsc::unbounded_channel();
3333        replace_data_event_sender(sender);
3334        let client = OKXDataClient::new(*OKX_CLIENT_ID, OKXDataClientConfig::default()).unwrap();
3335        let instrument_id = InstrumentId::from(instrument_id);
3336        crypto_future_btcusdt.id = instrument_id;
3337        crypto_future_btcusdt.raw_symbol = instrument_id.symbol;
3338
3339        if cached {
3340            client
3341                .http_client
3342                .cache_instrument(InstrumentAny::CryptoFuture(crypto_future_btcusdt));
3343        }
3344
3345        assert_eq!(
3346            client.book_channel(instrument_id, None, None),
3347            OKXBookChannel::Book
3348        );
3349    }
3350
3351    #[rstest]
3352    #[case(1, false)]
3353    #[case(5, false)]
3354    #[case(1, true)]
3355    #[case(5, true)]
3356    fn native_depth_replaces_snapshots_and_ignores_unsubscribed_data(
3357        currency_pair_btcusdt: CurrencyPair,
3358        #[case] limit: usize,
3359        #[case] spread: bool,
3360    ) {
3361        let instrument = InstrumentAny::CurrencyPair(currency_pair_btcusdt);
3362        let id = instrument.id();
3363        let frame: OKXWsFrame =
3364            serde_json::from_str(&load_test_json("ws_books_snapshot.json")).unwrap();
3365
3366        let OKXWsFrame::BookData { mut data, .. } = frame else {
3367            panic!("expected book data");
3368        };
3369
3370        if spread {
3371            for message in &mut data {
3372                for level in message.bids.iter_mut().chain(&mut message.asks) {
3373                    level.liquidated_orders_count = level.orders_count.clone();
3374                    level.orders_count = String::new();
3375                }
3376            }
3377        }
3378
3379        let subscriptions = AtomicMap::new();
3380        subscriptions.insert(id, limit);
3381        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
3382        let sender = sender.into();
3383        OKXDataClient::send_book_depth(
3384            &mut data,
3385            &instrument,
3386            &subscriptions,
3387            &sender,
3388            UnixNanos::from(103),
3389            spread,
3390        );
3391
3392        let DataEvent::Data(Data::BookDepth(initial)) = receiver.try_recv().unwrap() else {
3393            panic!("expected depth");
3394        };
3395
3396        assert_eq!(initial.instrument_id, id);
3397        assert_eq!(initial.sequence, 123_456);
3398        assert_eq!(initial.ts_event, UnixNanos::from(1_597_026_383_085_000_000));
3399        assert_eq!(initial.ts_init, UnixNanos::from(103));
3400        assert_eq!(initial.bids.len(), limit);
3401        assert_eq!(initial.asks.len(), limit);
3402        assert_eq!(initial.bid_counts.as_slice(), &[12, 1, 1, 1, 1][..limit]);
3403        assert_eq!(initial.ask_counts.as_slice(), &[13, 2, 1, 1, 1][..limit]);
3404
3405        if spread {
3406            data[0].bids[0].liquidated_orders_count = "invalid".to_string();
3407        } else {
3408            data[0].bids[0].orders_count = "invalid".to_string();
3409        }
3410
3411        OKXDataClient::send_book_depth(
3412            &mut data,
3413            &instrument,
3414            &subscriptions,
3415            &sender,
3416            UnixNanos::from(107),
3417            spread,
3418        );
3419        assert!(receiver.try_recv().is_err());
3420        data[0].bids.clear();
3421        data[0].asks.clear();
3422        data[0].seq_id = 17;
3423        OKXDataClient::send_book_depth(
3424            &mut data,
3425            &instrument,
3426            &subscriptions,
3427            &sender,
3428            UnixNanos::from(109),
3429            spread,
3430        );
3431
3432        let DataEvent::Data(Data::BookDepth(empty)) = receiver.try_recv().unwrap() else {
3433            panic!("expected empty depth");
3434        };
3435
3436        assert!(empty.bids.is_empty());
3437        assert!(empty.asks.is_empty());
3438        assert!(empty.bid_counts.is_empty());
3439        assert!(empty.ask_counts.is_empty());
3440        assert_eq!(empty.sequence, 17);
3441        assert_eq!(empty.ts_init, UnixNanos::from(109));
3442        subscriptions.remove(&id);
3443        OKXDataClient::send_book_depth(
3444            &mut data,
3445            &instrument,
3446            &subscriptions,
3447            &sender,
3448            UnixNanos::from(113),
3449            spread,
3450        );
3451        assert!(receiver.try_recv().is_err());
3452    }
3453
3454    struct DropSignal(Option<tokio::sync::oneshot::Sender<()>>);
3455
3456    impl Drop for DropSignal {
3457        fn drop(&mut self) {
3458            if let Some(sender) = self.0.take() {
3459                let _ = sender.send(());
3460            }
3461        }
3462    }
3463
3464    #[derive(Clone, Copy)]
3465    enum DataTaskBoundary {
3466        Reset,
3467        Dispose,
3468        RepeatedStop,
3469    }
3470
3471    fn both() -> AHashSet<OKXGreeksType> {
3472        [OKXGreeksType::Bs, OKXGreeksType::Pa].into_iter().collect()
3473    }
3474
3475    fn only(greeks_type: OKXGreeksType) -> AHashSet<OKXGreeksType> {
3476        [greeks_type].into_iter().collect()
3477    }
3478
3479    #[rstest]
3480    fn dispatch_parsed_data_emits_instrument_status() {
3481        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
3482        let instruments_by_symbol = Arc::new(AtomicMap::new());
3483        let status = InstrumentStatus::new(
3484            InstrumentId::from("USDG-SGD.OKX"),
3485            MarketStatusAction::Trading,
3486            UnixNanos::from(1u64),
3487            UnixNanos::from(2u64),
3488            None,
3489            None,
3490            Some(true),
3491            None,
3492            None,
3493        );
3494
3495        dispatch_parsed_data(
3496            NautilusWsMessage::InstrumentStatus(status),
3497            &sender.into(),
3498            &instruments_by_symbol,
3499        );
3500
3501        match receiver.try_recv().expect("instrument status event") {
3502            DataEvent::Data(Data::InstrumentStatus(received)) => assert_eq!(received, status),
3503            other => panic!("Expected DataEvent::Data(Data::InstrumentStatus(...)), was {other:?}"),
3504        }
3505        assert!(instruments_by_symbol.load().is_empty());
3506    }
3507
3508    #[rstest]
3509    #[case::sent_permanent(false, "60018")]
3510    #[case::unsent_permanent(true, "60018")]
3511    #[case::sent_transient(false, "60014")]
3512    #[case::unsent_transient(true, "60014")]
3513    fn rejected_book_subscription_preserves_channel_and_sync_state(
3514        #[case] sending: bool,
3515        #[case] code: &str,
3516    ) {
3517        let instrument_id = InstrumentId::from("OMI-USD.OKX");
3518        let mut pair = currency_pair_btcusdt();
3519        pair.id = instrument_id;
3520        pair.raw_symbol = Symbol::from("OMI-USD");
3521        let instrument = InstrumentAny::CurrencyPair(pair);
3522
3523        let instruments_by_symbol = Arc::new(AtomicMap::new());
3524        instruments_by_symbol.insert(Ustr::from("OMI-USD"), instrument);
3525        let book_channels = Arc::new(AtomicMap::new());
3526        book_channels.insert(instrument_id, OKXBookChannel::Book);
3527        let book_sync = BookSyncTracker::default();
3528        let subscribed_at = Instant::now()
3529            .checked_sub(Duration::from_secs(6))
3530            .expect("subscription timestamp");
3531        let gate = SnapshotGate::default();
3532        if sending {
3533            gate.lock().close();
3534        }
3535
3536        let cancel = book_sync.record_subscription(instrument_id, subscribed_at, gate.clone());
3537        let (sender, _receiver) = tokio::sync::mpsc::unbounded_channel();
3538        let http = offline_http_client();
3539        let update_lock = InstrumentUpdateLock::default();
3540        let mut quote_cache = QuoteCache::new();
3541        let mut funding_cache: AHashMap<Ustr, (Ustr, u64)> = AHashMap::new();
3542        let index_ticker_map = Arc::new(AtomicMap::new());
3543        let option_greeks_subs = Arc::new(AtomicMap::new());
3544        let task_group = TaskGroup::new();
3545        let tasks = task_group.spawner().expect("task spawner");
3546
3547        OKXDataClient::handle_ws_message(
3548            OKXWsMessage::SubscriptionFailed {
3549                channel: OKXWsChannel::Books,
3550                inst_id: Some(Ustr::from("OMI-USD")),
3551                code: code.to_string(),
3552                msg: "Channel does not exist".to_string(),
3553            },
3554            &sender.into(),
3555            &instruments_by_symbol,
3556            &http,
3557            &OKXDataClientConfig::default(),
3558            &update_lock,
3559            &book_channels,
3560            &book_sync,
3561            &AtomicMap::new(),
3562            &AtomicSet::new(),
3563            None,
3564            None,
3565            &mut quote_cache,
3566            &mut funding_cache,
3567            &index_ticker_map,
3568            &option_greeks_subs,
3569            BookChannelScope::Public,
3570            Duration::ZERO,
3571            &tasks,
3572            get_atomic_clock_realtime(),
3573        );
3574
3575        assert_eq!(
3576            book_channels.load().get(&instrument_id),
3577            Some(&OKXBookChannel::Book),
3578            "rejected subscription must preserve the channel selected for reconnect"
3579        );
3580        assert_eq!(
3581            book_sync
3582                .stale_books(Duration::from_secs(5), Instant::now())
3583                .len(),
3584            1,
3585            "rejected subscription must keep book synchronization state for recovery"
3586        );
3587        assert!(
3588            !cancel.is_cancelled(),
3589            "the initial snapshot wait keeps ownership until its deadline starts recovery"
3590        );
3591        gate.open();
3592        assert_eq!(
3593            book_sync.validate_sequence(instrument_id, true, &[(Some(-1), 42)], Instant::now()),
3594            BookSequenceOutcome::Accept,
3595            "a rejected subscription never suppresses a later snapshot"
3596        );
3597    }
3598
3599    #[rstest]
3600    fn reconnect_clears_quote_and_funding_caches() {
3601        let instrument_id = InstrumentId::from("OMI-USD.OKX");
3602        let mut pair = currency_pair_btcusdt();
3603        pair.id = instrument_id;
3604        pair.raw_symbol = Symbol::from("OMI-USD");
3605        let instrument = InstrumentAny::CurrencyPair(pair);
3606
3607        let instruments_by_symbol = Arc::new(AtomicMap::new());
3608        instruments_by_symbol.insert(Ustr::from("OMI-USD"), instrument);
3609        let book_channels = Arc::new(AtomicMap::new());
3610        let book_sync = BookSyncTracker::default();
3611        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
3612        let http = offline_http_client();
3613        let update_lock = InstrumentUpdateLock::default();
3614        let mut quote_cache = QuoteCache::new();
3615        quote_cache
3616            .process(
3617                instrument_id,
3618                Some(Price::from("1.0")),
3619                Some(Price::from("1.1")),
3620                Some(Quantity::from("1")),
3621                Some(Quantity::from("2")),
3622                UnixNanos::from(1),
3623                UnixNanos::from(2),
3624            )
3625            .expect("seed quote cache");
3626        let mut funding_cache =
3627            AHashMap::from([(Ustr::from("OMI-USD"), (Ustr::from("0.0001"), 1))]);
3628        let index_ticker_map = Arc::new(AtomicMap::new());
3629        let option_greeks_subs = Arc::new(AtomicMap::new());
3630        let task_group = TaskGroup::new();
3631        let tasks = task_group.spawner().expect("task spawner");
3632
3633        OKXDataClient::handle_ws_message(
3634            OKXWsMessage::Reconnected,
3635            &sender.clone().into(),
3636            &instruments_by_symbol,
3637            &http,
3638            &OKXDataClientConfig::default(),
3639            &update_lock,
3640            &book_channels,
3641            &book_sync,
3642            &AtomicMap::new(),
3643            &AtomicSet::new(),
3644            None,
3645            None,
3646            &mut quote_cache,
3647            &mut funding_cache,
3648            &index_ticker_map,
3649            &option_greeks_subs,
3650            BookChannelScope::Public,
3651            Duration::ZERO,
3652            &tasks,
3653            get_atomic_clock_realtime(),
3654        );
3655
3656        assert!(
3657            quote_cache.is_empty(),
3658            "reconnect must drop quotes from the previous generation"
3659        );
3660        assert!(
3661            funding_cache.is_empty(),
3662            "reconnect must drop funding rates from the previous generation"
3663        );
3664
3665        OKXDataClient::handle_ws_message(
3666            OKXWsMessage::ChannelData {
3667                channel: OKXWsChannel::BboTbt,
3668                inst_id: Some(Ustr::from("OMI-USD")),
3669                data: json!([{
3670                    "asks": [{
3671                        "price": "1.2",
3672                        "size": "3",
3673                        "liquidated_orders_count": "0",
3674                        "orders_count": "1"
3675                    }],
3676                    "bids": [],
3677                    "seqId": 1,
3678                    "ts": "3"
3679                }]),
3680            },
3681            &sender.clone().into(),
3682            &instruments_by_symbol,
3683            &http,
3684            &OKXDataClientConfig::default(),
3685            &update_lock,
3686            &book_channels,
3687            &book_sync,
3688            &AtomicMap::new(),
3689            &AtomicSet::new(),
3690            None,
3691            None,
3692            &mut quote_cache,
3693            &mut funding_cache,
3694            &index_ticker_map,
3695            &option_greeks_subs,
3696            BookChannelScope::Public,
3697            Duration::ZERO,
3698            &tasks,
3699            get_atomic_clock_realtime(),
3700        );
3701
3702        assert!(
3703            receiver.try_recv().is_err(),
3704            "partial BBO after reconnect must not invent a quote from the previous generation"
3705        );
3706        assert!(quote_cache.is_empty());
3707
3708        OKXDataClient::handle_ws_message(
3709            OKXWsMessage::ChannelData {
3710                channel: OKXWsChannel::BboTbt,
3711                inst_id: Some(Ustr::from("OMI-USD")),
3712                data: json!([{
3713                    "asks": [{
3714                        "price": "1.2",
3715                        "size": "3",
3716                        "liquidated_orders_count": "0",
3717                        "orders_count": "1"
3718                    }],
3719                    "bids": [{
3720                        "price": "1.0",
3721                        "size": "4",
3722                        "liquidated_orders_count": "0",
3723                        "orders_count": "1"
3724                    }],
3725                    "seqId": 2,
3726                    "ts": "4"
3727                }]),
3728            },
3729            &sender.into(),
3730            &instruments_by_symbol,
3731            &http,
3732            &OKXDataClientConfig::default(),
3733            &update_lock,
3734            &book_channels,
3735            &book_sync,
3736            &AtomicMap::new(),
3737            &AtomicSet::new(),
3738            None,
3739            None,
3740            &mut quote_cache,
3741            &mut funding_cache,
3742            &index_ticker_map,
3743            &option_greeks_subs,
3744            BookChannelScope::Public,
3745            Duration::ZERO,
3746            &tasks,
3747            get_atomic_clock_realtime(),
3748        );
3749
3750        match receiver.try_recv().expect("complete BBO after reconnect") {
3751            DataEvent::Data(Data::Quote(quote)) => {
3752                assert_eq!(quote.instrument_id, instrument_id);
3753                assert_eq!(quote.bid_price, Price::from("1.0"));
3754                assert_eq!(quote.ask_price, Price::from("1.2"));
3755                assert_eq!(quote.bid_size, Quantity::from("4"));
3756                assert_eq!(quote.ask_size, Quantity::from("3"));
3757            }
3758            other => panic!("Expected DataEvent::Data(Data::Quote), was {other:?}"),
3759        }
3760    }
3761
3762    #[rstest]
3763    fn index_ticker_fan_out_emits_subscribed_symbols_in_sorted_order() {
3764        // Five full symbols sharing one base pair, registered in non-sorted order
3765        let symbols = [
3766            "BTC-USDT-SWAP",
3767            "BTC-USDT-241227",
3768            "BTC-USDT-240628",
3769            "BTC-USDT-250328",
3770            "BTC-USDT-240906",
3771        ];
3772
3773        let instruments_by_symbol = Arc::new(AtomicMap::new());
3774
3775        for symbol in symbols {
3776            let mut pair = currency_pair_btcusdt();
3777            let id = format!("{symbol}.OKX");
3778            pair.id = InstrumentId::from(id.as_str());
3779            pair.raw_symbol = Symbol::from(symbol);
3780            instruments_by_symbol.insert(Ustr::from(symbol), InstrumentAny::CurrencyPair(pair));
3781        }
3782
3783        let index_ticker_map = Arc::new(AtomicMap::new());
3784        index_ticker_map.insert(
3785            Ustr::from("BTC-USDT"),
3786            AHashSet::from_iter(symbols.iter().map(|symbol| Ustr::from(symbol))),
3787        );
3788
3789        let book_channels = Arc::new(AtomicMap::new());
3790        let book_sync = BookSyncTracker::default();
3791        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
3792        let http = offline_http_client();
3793        let update_lock = InstrumentUpdateLock::default();
3794        let mut quote_cache = QuoteCache::new();
3795        let mut funding_cache = AHashMap::new();
3796        let option_greeks_subs = Arc::new(AtomicMap::new());
3797        let task_group = TaskGroup::new();
3798        let tasks = task_group.spawner().expect("task spawner");
3799
3800        OKXDataClient::handle_ws_message(
3801            OKXWsMessage::ChannelData {
3802                channel: OKXWsChannel::IndexTickers,
3803                inst_id: Some(Ustr::from("BTC-USDT")),
3804                data: json!([{
3805                    "instId": "BTC-USDT",
3806                    "idxPx": "65000.1",
3807                    "high24h": "66000.0",
3808                    "low24h": "64000.0",
3809                    "open24h": "64500.0",
3810                    "sodUtc0": "64500.0",
3811                    "sodUtc8": "64600.0",
3812                    "ts": "1710000000000"
3813                }]),
3814            },
3815            &sender.into(),
3816            &instruments_by_symbol,
3817            &http,
3818            &OKXDataClientConfig::default(),
3819            &update_lock,
3820            &book_channels,
3821            &book_sync,
3822            &AtomicMap::new(),
3823            &AtomicSet::new(),
3824            None,
3825            None,
3826            &mut quote_cache,
3827            &mut funding_cache,
3828            &index_ticker_map,
3829            &option_greeks_subs,
3830            BookChannelScope::Public,
3831            Duration::ZERO,
3832            &tasks,
3833            get_atomic_clock_realtime(),
3834        );
3835
3836        let mut instrument_ids = Vec::new();
3837
3838        while let Ok(event) = receiver.try_recv() {
3839            match event {
3840                DataEvent::Data(Data::IndexPrice(update)) => {
3841                    instrument_ids.push(update.instrument_id);
3842                }
3843                other => panic!("Expected DataEvent::Data(Data::IndexPrice), was {other:?}"),
3844            }
3845        }
3846
3847        assert_eq!(
3848            instrument_ids,
3849            [
3850                "BTC-USDT-240628.OKX",
3851                "BTC-USDT-240906.OKX",
3852                "BTC-USDT-241227.OKX",
3853                "BTC-USDT-250328.OKX",
3854                "BTC-USDT-SWAP.OKX",
3855            ]
3856            .map(InstrumentId::from)
3857        );
3858    }
3859
3860    #[rstest]
3861    fn rpi_missing_recovery_transport_restores_on_next_snapshot() {
3862        let instrument_id = InstrumentId::from("OMI-USD.OKX");
3863        let mut pair = currency_pair_btcusdt();
3864        pair.id = instrument_id;
3865        pair.raw_symbol = Symbol::from("OMI-USD");
3866        pair.price_precision = 7;
3867        pair.size_precision = 3;
3868        pair.price_increment = Price::from("0.0000001");
3869        pair.size_increment = Quantity::from("0.001");
3870        let instrument = InstrumentAny::CurrencyPair(pair);
3871
3872        let instruments_by_symbol = Arc::new(AtomicMap::new());
3873        instruments_by_symbol.insert(Ustr::from("OMI-USD"), instrument);
3874        let book_channels = Arc::new(AtomicMap::new());
3875        book_channels.insert(instrument_id, OKXBookChannel::BooksRpi);
3876        let book_sync = BookSyncTracker::default();
3877        book_sync.record_subscription(instrument_id, Instant::now(), SnapshotGate::default());
3878        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
3879        let http = offline_http_client();
3880        let update_lock = InstrumentUpdateLock::default();
3881        let index_ticker_map = Arc::new(AtomicMap::new());
3882        let option_greeks_subs = Arc::new(AtomicMap::new());
3883        let task_group = TaskGroup::new();
3884        let tasks = task_group.spawner().expect("task spawner");
3885        let mut quote_cache = QuoteCache::new();
3886        let mut funding_cache = AHashMap::new();
3887
3888        let snapshot = rpi_book_message("ws_books_rpi_snapshot.json");
3889        let update = rpi_book_message("ws_books_rpi_update.json");
3890        let mut gap = rpi_book_message("ws_books_rpi_update.json");
3891        let OKXWsMessage::RpiBookData { data, .. } = &mut gap else {
3892            unreachable!()
3893        };
3894        data[0].prev_seq_id -= 1;
3895
3896        let mut handle = |message| {
3897            OKXDataClient::handle_ws_message(
3898                message,
3899                &sender.clone().into(),
3900                &instruments_by_symbol,
3901                &http,
3902                &OKXDataClientConfig::default(),
3903                &update_lock,
3904                &book_channels,
3905                &book_sync,
3906                &AtomicMap::new(),
3907                &AtomicSet::new(),
3908                None,
3909                None,
3910                &mut quote_cache,
3911                &mut funding_cache,
3912                &index_ticker_map,
3913                &option_greeks_subs,
3914                BookChannelScope::Public,
3915                Duration::ZERO,
3916                &tasks,
3917                get_atomic_clock_realtime(),
3918            );
3919        };
3920
3921        handle(snapshot);
3922        assert!(matches!(receiver.try_recv(), Ok(DataEvent::Data(_))));
3923        assert!(matches!(
3924            receiver.try_recv(),
3925            Err(tokio::sync::mpsc::error::TryRecvError::Empty)
3926        ));
3927
3928        handle(gap);
3929        handle(update);
3930        assert!(matches!(
3931            receiver.try_recv(),
3932            Err(tokio::sync::mpsc::error::TryRecvError::Empty)
3933        ));
3934
3935        let mut recovered_snapshot = rpi_book_message("ws_books_rpi_snapshot.json");
3936        let OKXWsMessage::RpiBookData { data, .. } = &mut recovered_snapshot else {
3937            unreachable!()
3938        };
3939        data[0].seq_id = 2_000;
3940        handle(rpi_book_message("ws_books_rpi_snapshot.json"));
3941        assert!(matches!(receiver.try_recv(), Ok(DataEvent::Data(_))));
3942        assert!(matches!(
3943            receiver.try_recv(),
3944            Err(tokio::sync::mpsc::error::TryRecvError::Empty)
3945        ));
3946
3947        handle(OKXWsMessage::Reconnected);
3948        handle(recovered_snapshot);
3949        assert!(matches!(receiver.try_recv(), Ok(DataEvent::Data(_))));
3950        assert!(matches!(
3951            receiver.try_recv(),
3952            Err(tokio::sync::mpsc::error::TryRecvError::Empty)
3953        ));
3954    }
3955
3956    #[rstest]
3957    #[case(None, both())]
3958    #[case(Some(("other_key", json!("value"))), both())]
3959    #[case(
3960        Some(("greeks_convention", json!("BLACK_SCHOLES"))),
3961        only(OKXGreeksType::Bs)
3962    )]
3963    #[case(
3964        Some(("greeks_convention", json!("PRICE_ADJUSTED"))),
3965        only(OKXGreeksType::Pa)
3966    )]
3967    #[case(
3968        Some(("greeks_convention", json!("black_scholes"))),
3969        only(OKXGreeksType::Bs)
3970    )]
3971    #[case(
3972        Some(("greeks_convention", json!("price_adjusted"))),
3973        only(OKXGreeksType::Pa)
3974    )]
3975    #[case(
3976        Some((
3977            "greeks_convention",
3978            json!(["BLACK_SCHOLES", "PRICE_ADJUSTED"])
3979        )),
3980        both()
3981    )]
3982    #[case(
3983        Some(("greeks_convention", json!(["PRICE_ADJUSTED"]))),
3984        only(OKXGreeksType::Pa)
3985    )]
3986    #[case(
3987        Some((
3988            "greeks_convention",
3989            json!(["BLACK_SCHOLES", "black_scholes"])
3990        )),
3991        only(OKXGreeksType::Bs)
3992    )]
3993    #[case(
3994        Some(("greeks_convention", json!(["BOGUS", "PRICE_ADJUSTED"]))),
3995        only(OKXGreeksType::Pa)
3996    )]
3997    #[case(Some(("greeks_convention", json!(["BOGUS"]))), both())]
3998    #[case(Some(("greeks_convention", json!(1))), both())]
3999    #[case(Some(("greeks_convention", json!(null))), both())]
4000    #[case(Some(("greeks_convention", json!(true))), both())]
4001    #[case(Some(("greeks_convention", json!({"nested": "object"}))), both())]
4002    #[case(Some(("greeks_convention", json!("BOGUS"))), both())]
4003    fn parse_conventions(
4004        #[case] entry: Option<(&str, Value)>,
4005        #[case] expected: AHashSet<OKXGreeksType>,
4006    ) {
4007        let params = entry.map(|(key, value)| Params::new([(key.to_string(), value)].into()));
4008        let result = parse_greeks_conventions_from_params(params.as_ref());
4009        assert_eq!(result, expected);
4010    }
4011
4012    fn rpi_book_message(filename: &str) -> OKXWsMessage {
4013        let frame: OKXWsFrame = serde_json::from_str(&load_test_json(filename)).unwrap();
4014        let OKXWsFrame::RpiBookData { arg, action, data } = frame else {
4015            panic!("expected RPI book data");
4016        };
4017        OKXWsMessage::RpiBookData { arg, action, data }
4018    }
4019
4020    fn swap_definition(tick_sz: &str) -> Value {
4021        json!({
4022            "alias": "",
4023            "baseCcy": "",
4024            "category": "1",
4025            "ctMult": "1",
4026            "ctType": "linear",
4027            "ctVal": "0.01",
4028            "ctValCcy": "BTC",
4029            "expTime": "",
4030            "instFamily": "BTC-USDT",
4031            "instId": "BTC-USDT-SWAP",
4032            "instType": "SWAP",
4033            "lever": "125",
4034            "listTime": "1611916828000",
4035            "lotSz": "1",
4036            "maxIcebergSz": "100000000.0000000000000000",
4037            "maxLmtAmt": "20000000",
4038            "maxLmtSz": "100000000",
4039            "maxMktAmt": "",
4040            "maxMktSz": "30000",
4041            "maxStopSz": "30000",
4042            "maxTriggerSz": "100000000.0000000000000000",
4043            "maxTwapSz": "100000000.0000000000000000",
4044            "minSz": "1",
4045            "optType": "",
4046            "quoteCcy": "",
4047            "ruleType": "normal",
4048            "settleCcy": "USDT",
4049            "state": "live",
4050            "stk": "",
4051            "tickSz": tick_sz,
4052            "uly": "BTC-USDT"
4053        })
4054    }
4055
4056    fn ws_instruments_message(definition: Value) -> OKXWsMessage {
4057        let instrument: OKXInstrument =
4058            serde_json::from_value(definition).expect("valid OKXInstrument");
4059        OKXWsMessage::Instruments(vec![instrument])
4060    }
4061
4062    fn offline_http_client() -> OKXHttpClient {
4063        OKXHttpClient::new(
4064            Some("http://127.0.0.1:9".to_string()),
4065            5,
4066            0,
4067            1,
4068            1,
4069            OKXEnvironment::Live,
4070            None,
4071        )
4072        .expect("http client")
4073    }
4074
4075    fn offline_ws_client() -> OKXWebSocketClient {
4076        OKXWebSocketClient::new(
4077            Some("ws://127.0.0.1:9".to_string()),
4078            None,
4079            None,
4080            None,
4081            None,
4082            Some(OKX_WS_HEARTBEAT_SECS),
4083            None,
4084            TransportBackend::default(),
4085            None,
4086        )
4087        .expect("ws client")
4088    }
4089
4090    fn handle_instruments_message(
4091        sender: &EventSender<DataEvent>,
4092        instruments_by_symbol: &Arc<AtomicMap<Ustr, InstrumentAny>>,
4093        http_client: &OKXHttpClient,
4094        config: &OKXDataClientConfig,
4095        recovery_ws: Option<&OKXWebSocketClient>,
4096        business_ws: Option<&OKXWebSocketClient>,
4097        message: OKXWsMessage,
4098    ) {
4099        let book_channels = Arc::new(AtomicMap::new());
4100        let book_sync = BookSyncTracker::default();
4101        let update_lock = InstrumentUpdateLock::default();
4102        let mut quote_cache = QuoteCache::new();
4103        let mut funding_cache = AHashMap::new();
4104        let index_ticker_map = Arc::new(AtomicMap::new());
4105        let option_greeks_subs = Arc::new(AtomicMap::new());
4106        let task_group = TaskGroup::new();
4107        let tasks = task_group.spawner().expect("task spawner");
4108
4109        OKXDataClient::handle_ws_message(
4110            message,
4111            sender,
4112            instruments_by_symbol,
4113            http_client,
4114            config,
4115            &update_lock,
4116            &book_channels,
4117            &book_sync,
4118            &AtomicMap::new(),
4119            &AtomicSet::new(),
4120            recovery_ws,
4121            business_ws,
4122            &mut quote_cache,
4123            &mut funding_cache,
4124            &index_ticker_map,
4125            &option_greeks_subs,
4126            BookChannelScope::Public,
4127            Duration::ZERO,
4128            &tasks,
4129            get_atomic_clock_realtime(),
4130        );
4131    }
4132
4133    #[rstest]
4134    fn ws_instruments_publishes_new_definition_and_status() {
4135        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
4136        let instruments_by_symbol = Arc::new(AtomicMap::new());
4137        let http = offline_http_client();
4138        let ws_public = offline_ws_client();
4139        let ws_business = offline_ws_client();
4140
4141        handle_instruments_message(
4142            &sender.into(),
4143            &instruments_by_symbol,
4144            &http,
4145            &OKXDataClientConfig::default(),
4146            Some(&ws_public),
4147            Some(&ws_business),
4148            ws_instruments_message(swap_definition("0.1")),
4149        );
4150
4151        match receiver.try_recv().expect("instrument event") {
4152            DataEvent::Data(Data::Instrument(instrument)) => {
4153                assert_eq!(instrument.id(), InstrumentId::from("BTC-USDT-SWAP.OKX"));
4154                assert_eq!(instrument.price_increment(), Price::from("0.1"));
4155            }
4156            other => panic!("Expected DataEvent::Data(Data::Instrument(...)), was {other:?}"),
4157        }
4158
4159        match receiver.try_recv().expect("instrument status event") {
4160            DataEvent::Data(Data::InstrumentStatus(status)) => {
4161                assert_eq!(
4162                    status.instrument_id,
4163                    InstrumentId::from("BTC-USDT-SWAP.OKX")
4164                );
4165                assert_eq!(status.action, MarketStatusAction::Trading);
4166            }
4167            other => panic!("Expected DataEvent::Data(Data::InstrumentStatus(...)), was {other:?}"),
4168        }
4169        assert!(receiver.try_recv().is_err());
4170
4171        let symbol = Ustr::from("BTC-USDT-SWAP");
4172        let cached = instruments_by_symbol
4173            .get_cloned(&symbol)
4174            .expect("instrument cached in the shared cache");
4175        assert_eq!(cached.id(), InstrumentId::from("BTC-USDT-SWAP.OKX"));
4176        assert_eq!(cached.price_increment(), Price::from("0.1"));
4177        assert!(
4178            http.get_instrument(&symbol).is_some(),
4179            "HTTP client cache must be updated before publishing"
4180        );
4181        assert!(
4182            ws_public.instruments_snapshot().contains_key(&symbol),
4183            "public WebSocket cache must be updated before publishing"
4184        );
4185        assert!(
4186            ws_business.instruments_snapshot().contains_key(&symbol),
4187            "business WebSocket cache must be updated before publishing"
4188        );
4189    }
4190
4191    #[rstest]
4192    fn ws_instruments_unchanged_definition_emits_status_only() {
4193        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
4194        let instruments_by_symbol = Arc::new(AtomicMap::new());
4195        let http = offline_http_client();
4196
4197        for _ in 0..2 {
4198            handle_instruments_message(
4199                &sender.clone().into(),
4200                &instruments_by_symbol,
4201                &http,
4202                &OKXDataClientConfig::default(),
4203                None,
4204                None,
4205                ws_instruments_message(swap_definition("0.1")),
4206            );
4207        }
4208
4209        assert!(matches!(
4210            receiver.try_recv(),
4211            Ok(DataEvent::Data(Data::Instrument(_)))
4212        ));
4213        assert!(matches!(
4214            receiver.try_recv(),
4215            Ok(DataEvent::Data(Data::InstrumentStatus(_)))
4216        ));
4217
4218        match receiver
4219            .try_recv()
4220            .expect("status event for repeat definition")
4221        {
4222            DataEvent::Data(Data::InstrumentStatus(status)) => {
4223                assert_eq!(
4224                    status.instrument_id,
4225                    InstrumentId::from("BTC-USDT-SWAP.OKX")
4226                );
4227            }
4228            other => panic!("Expected DataEvent::Data(Data::InstrumentStatus(...)), was {other:?}"),
4229        }
4230        assert!(
4231            receiver.try_recv().is_err(),
4232            "unchanged definition must not be republished"
4233        );
4234    }
4235
4236    #[rstest]
4237    fn ws_instruments_changed_definition_is_republished() {
4238        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
4239        let instruments_by_symbol = Arc::new(AtomicMap::new());
4240        let http = offline_http_client();
4241
4242        handle_instruments_message(
4243            &sender.clone().into(),
4244            &instruments_by_symbol,
4245            &http,
4246            &OKXDataClientConfig::default(),
4247            None,
4248            None,
4249            ws_instruments_message(swap_definition("0.1")),
4250        );
4251        handle_instruments_message(
4252            &sender.into(),
4253            &instruments_by_symbol,
4254            &http,
4255            &OKXDataClientConfig::default(),
4256            None,
4257            None,
4258            ws_instruments_message(swap_definition("0.5")),
4259        );
4260
4261        assert!(matches!(
4262            receiver.try_recv(),
4263            Ok(DataEvent::Data(Data::Instrument(_)))
4264        ));
4265        assert!(matches!(
4266            receiver.try_recv(),
4267            Ok(DataEvent::Data(Data::InstrumentStatus(_)))
4268        ));
4269
4270        match receiver.try_recv().expect("republished instrument") {
4271            DataEvent::Data(Data::Instrument(instrument)) => {
4272                assert_eq!(instrument.id(), InstrumentId::from("BTC-USDT-SWAP.OKX"));
4273                assert_eq!(instrument.price_increment(), Price::from("0.5"));
4274            }
4275            other => panic!("Expected DataEvent::Data(Data::Instrument(...)), was {other:?}"),
4276        }
4277
4278        match receiver
4279            .try_recv()
4280            .expect("status for republished instrument")
4281        {
4282            DataEvent::Data(Data::InstrumentStatus(status)) => {
4283                assert_eq!(
4284                    status.instrument_id,
4285                    InstrumentId::from("BTC-USDT-SWAP.OKX")
4286                );
4287            }
4288            other => panic!("Expected DataEvent::Data(Data::InstrumentStatus(...)), was {other:?}"),
4289        }
4290        assert!(receiver.try_recv().is_err());
4291
4292        let cached = instruments_by_symbol
4293            .get_cloned(&Ustr::from("BTC-USDT-SWAP"))
4294            .expect("instrument cached in the shared cache");
4295        assert_eq!(cached.price_increment(), Price::from("0.5"));
4296    }
4297
4298    #[rstest]
4299    fn ws_instruments_invalid_definition_emits_status_only() {
4300        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
4301        let instruments_by_symbol = Arc::new(AtomicMap::new());
4302        let http = offline_http_client();
4303        let mut definition = swap_definition("0.1");
4304        definition["uly"] = json!("");
4305
4306        handle_instruments_message(
4307            &sender.into(),
4308            &instruments_by_symbol,
4309            &http,
4310            &OKXDataClientConfig::default(),
4311            None,
4312            None,
4313            ws_instruments_message(definition),
4314        );
4315
4316        match receiver
4317            .try_recv()
4318            .expect("status event for invalid definition")
4319        {
4320            DataEvent::Data(Data::InstrumentStatus(status)) => {
4321                assert_eq!(
4322                    status.instrument_id,
4323                    InstrumentId::from("BTC-USDT-SWAP.OKX")
4324                );
4325            }
4326            other => panic!("Expected DataEvent::Data(Data::InstrumentStatus(...)), was {other:?}"),
4327        }
4328        assert!(
4329            receiver.try_recv().is_err(),
4330            "invalid definition must not publish an instrument event"
4331        );
4332        assert!(instruments_by_symbol.load().is_empty());
4333    }
4334
4335    #[rstest]
4336    fn ws_instruments_batch_publishes_each_valid_definition() {
4337        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
4338        let instruments_by_symbol = Arc::new(AtomicMap::new());
4339        let http = offline_http_client();
4340        let mut eth_definition = swap_definition("0.01");
4341        eth_definition["instId"] = json!("ETH-USDT-SWAP");
4342        eth_definition["instFamily"] = json!("ETH-USDT");
4343        eth_definition["uly"] = json!("ETH-USDT");
4344        let batch = OKXWsMessage::Instruments(vec![
4345            serde_json::from_value(swap_definition("0.1")).expect("valid OKXInstrument"),
4346            serde_json::from_value(eth_definition).expect("valid OKXInstrument"),
4347        ]);
4348
4349        handle_instruments_message(
4350            &sender.into(),
4351            &instruments_by_symbol,
4352            &http,
4353            &OKXDataClientConfig::default(),
4354            None,
4355            None,
4356            batch,
4357        );
4358
4359        let mut published = Vec::new();
4360        let mut statuses = Vec::new();
4361
4362        while let Ok(event) = receiver.try_recv() {
4363            match event {
4364                DataEvent::Data(Data::Instrument(instrument)) => published.push(instrument.id()),
4365                DataEvent::Data(Data::InstrumentStatus(status)) => {
4366                    statuses.push(status.instrument_id);
4367                }
4368                other => panic!("Unexpected event {other:?}"),
4369            }
4370        }
4371
4372        assert_eq!(
4373            published,
4374            vec![
4375                InstrumentId::from("BTC-USDT-SWAP.OKX"),
4376                InstrumentId::from("ETH-USDT-SWAP.OKX")
4377            ],
4378            "every valid batch item must publish its definition"
4379        );
4380        assert_eq!(
4381            statuses,
4382            vec![
4383                InstrumentId::from("BTC-USDT-SWAP.OKX"),
4384                InstrumentId::from("ETH-USDT-SWAP.OKX")
4385            ],
4386            "every batch item must keep its status event"
4387        );
4388        assert_eq!(instruments_by_symbol.load().len(), 2);
4389    }
4390
4391    #[rstest]
4392    fn ws_instruments_respects_contract_type_filter() {
4393        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
4394        let instruments_by_symbol = Arc::new(AtomicMap::new());
4395        let http = offline_http_client();
4396        let config = OKXDataClientConfig::builder()
4397            .contract_types(vec![OKXContractType::Inverse])
4398            .build();
4399
4400        handle_instruments_message(
4401            &sender.clone().into(),
4402            &instruments_by_symbol,
4403            &http,
4404            &config,
4405            None,
4406            None,
4407            ws_instruments_message(swap_definition("0.1")),
4408        );
4409
4410        match receiver.try_recv().expect("status event") {
4411            DataEvent::Data(Data::InstrumentStatus(status)) => {
4412                assert_eq!(
4413                    status.instrument_id,
4414                    InstrumentId::from("BTC-USDT-SWAP.OKX")
4415                );
4416            }
4417            other => panic!("Expected DataEvent::Data(Data::InstrumentStatus(...)), was {other:?}"),
4418        }
4419        assert!(
4420            receiver.try_recv().is_err(),
4421            "a definition excluded by the contract type filter must not publish"
4422        );
4423        assert!(
4424            instruments_by_symbol.load().is_empty(),
4425            "a filtered definition must not enter the instrument cache"
4426        );
4427
4428        let inverse_item = test_payload("http_get_instruments_swap.json")["data"][0].clone();
4429        assert_eq!(inverse_item["instId"], json!("BTC-USD-SWAP"));
4430        assert_eq!(inverse_item["ctType"], json!("inverse"));
4431        handle_instruments_message(
4432            &sender.into(),
4433            &instruments_by_symbol,
4434            &http,
4435            &config,
4436            None,
4437            None,
4438            ws_instruments_message(inverse_item),
4439        );
4440
4441        match receiver.try_recv().expect("instrument event") {
4442            DataEvent::Data(Data::Instrument(instrument)) => {
4443                assert_eq!(instrument.id(), InstrumentId::from("BTC-USD-SWAP.OKX"));
4444            }
4445            other => panic!("Expected DataEvent::Data(Data::Instrument(...)), was {other:?}"),
4446        }
4447        assert!(matches!(
4448            receiver.try_recv(),
4449            Ok(DataEvent::Data(Data::InstrumentStatus(_)))
4450        ));
4451        assert_eq!(instruments_by_symbol.load().len(), 1);
4452    }
4453
4454    #[rstest]
4455    fn ws_instruments_respects_family_filter() {
4456        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
4457        let instruments_by_symbol = Arc::new(AtomicMap::new());
4458        let http = offline_http_client();
4459        let config = OKXDataClientConfig::builder()
4460            .instrument_types(vec![OKXInstrumentType::Swap])
4461            .instrument_families(vec!["BTC-USDT".to_string()])
4462            .build();
4463        let mut eth_definition = swap_definition("0.01");
4464        eth_definition["instId"] = json!("ETH-USDT-SWAP");
4465        eth_definition["instFamily"] = json!("ETH-USDT");
4466        eth_definition["uly"] = json!("ETH-USDT");
4467
4468        handle_instruments_message(
4469            &sender.clone().into(),
4470            &instruments_by_symbol,
4471            &http,
4472            &config,
4473            None,
4474            None,
4475            ws_instruments_message(eth_definition),
4476        );
4477
4478        match receiver.try_recv().expect("status event") {
4479            DataEvent::Data(Data::InstrumentStatus(status)) => {
4480                assert_eq!(
4481                    status.instrument_id,
4482                    InstrumentId::from("ETH-USDT-SWAP.OKX")
4483                );
4484            }
4485            other => panic!("Expected DataEvent::Data(Data::InstrumentStatus(...)), was {other:?}"),
4486        }
4487        assert!(
4488            receiver.try_recv().is_err(),
4489            "a definition outside the configured families must not publish"
4490        );
4491        assert!(instruments_by_symbol.load().is_empty());
4492
4493        handle_instruments_message(
4494            &sender.into(),
4495            &instruments_by_symbol,
4496            &http,
4497            &config,
4498            None,
4499            None,
4500            ws_instruments_message(swap_definition("0.1")),
4501        );
4502
4503        match receiver.try_recv().expect("instrument event") {
4504            DataEvent::Data(Data::Instrument(instrument)) => {
4505                assert_eq!(instrument.id(), InstrumentId::from("BTC-USDT-SWAP.OKX"));
4506            }
4507            other => panic!("Expected DataEvent::Data(Data::Instrument(...)), was {other:?}"),
4508        }
4509        assert!(matches!(
4510            receiver.try_recv(),
4511            Ok(DataEvent::Data(Data::InstrumentStatus(_)))
4512        ));
4513        assert_eq!(instruments_by_symbol.load().len(), 1);
4514    }
4515
4516    #[rstest]
4517    fn data_client_rejects_duplicate_configured_families() {
4518        let config = OKXDataClientConfig::builder()
4519            .instrument_families(vec!["BTC-USDT".to_string(), "BTC-USDT".to_string()])
4520            .build();
4521        let error = OKXDataClient::new(ClientId::from("OKX"), config)
4522            .expect_err("duplicate config must fail before client setup");
4523
4524        assert_eq!(
4525            error.downcast_ref::<ConfigError>(),
4526            Some(&ConfigError::duplicate("instrument_families", None))
4527        );
4528    }
4529
4530    #[rstest]
4531    fn data_client_rejects_duplicate_configured_types() {
4532        let config = OKXDataClientConfig::builder()
4533            .instrument_types(vec![OKXInstrumentType::Swap, OKXInstrumentType::Swap])
4534            .build();
4535        let error = OKXDataClient::new(ClientId::from("OKX"), config)
4536            .expect_err("duplicate config must fail before client setup");
4537
4538        assert_eq!(
4539            error.downcast_ref::<ConfigError>(),
4540            Some(&ConfigError::duplicate("instrument_types", None))
4541        );
4542    }
4543
4544    #[rstest]
4545    fn definition_in_scope_matches_events_family_on_series_id() {
4546        let okx_inst = OKXInstrument {
4547            inst_type: OKXInstrumentType::Events,
4548            inst_id: Ustr::from("BTC-ABOVE-DAILY-260224-1600-65000"),
4549            inst_id_code: Some(1_000_000_001),
4550            uly: Ustr::from(""),
4551            inst_family: Ustr::from(""),
4552            series_id: Some(Ustr::from("BTC-ABOVE-DAILY")),
4553            inst_category: Some(crate::common::enums::OKXInstrumentCategory::Crypto),
4554            group_id: None,
4555            init_px_lmt_pct: String::new(),
4556            float_px_lmt_pct: String::new(),
4557            max_px_lmt_pct: String::new(),
4558            base_ccy: Ustr::from(""),
4559            quote_ccy: Ustr::from("USDT"),
4560            settle_ccy: Ustr::from("USDT"),
4561            ct_val: String::new(),
4562            ct_mult: String::new(),
4563            ct_val_ccy: String::new(),
4564            opt_type: crate::common::enums::OKXOptionType::None,
4565            stk: String::new(),
4566            list_time: Some(1_769_697_132_335),
4567            exp_time: Some(1_769_700_732_335),
4568            lever: String::new(),
4569            tick_sz: "0.001".to_string(),
4570            lot_sz: "1".to_string(),
4571            min_sz: "1".to_string(),
4572            ct_type: OKXContractType::None,
4573            state: OKXInstrumentStatus::Settling,
4574            rule_type: "normal".to_string(),
4575            max_lmt_sz: "1000000".to_string(),
4576            max_mkt_sz: "1000000".to_string(),
4577            max_lmt_amt: String::new(),
4578            max_mkt_amt: String::new(),
4579            max_twap_sz: String::new(),
4580            max_iceberg_sz: String::new(),
4581            max_trigger_sz: String::new(),
4582            max_stop_sz: String::new(),
4583            rpi: None,
4584            rpi_min_level: None,
4585            rpi_min_px_band: None,
4586            trade_quote_ccy_list: Vec::new(),
4587        };
4588        let instrument = crate::common::parse::parse_event_contract_instrument(
4589            &okx_inst,
4590            None,
4591            None,
4592            UnixNanos::from(1u64),
4593        )
4594        .expect("parse events instrument");
4595        let matching = OKXDataClientConfig::builder()
4596            .instrument_types(vec![OKXInstrumentType::Events])
4597            .instrument_families(vec!["BTC-ABOVE-DAILY".to_string()])
4598            .build();
4599        let other = OKXDataClientConfig::builder()
4600            .instrument_types(vec![OKXInstrumentType::Events])
4601            .instrument_families(vec!["ETH-ABOVE-DAILY".to_string()])
4602            .build();
4603
4604        assert!(definition_in_scope(&matching, &okx_inst, &instrument));
4605        assert!(!definition_in_scope(&other, &okx_inst, &instrument));
4606    }
4607
4608    #[tokio::test]
4609    async fn ws_definition_matching_rest_fetch_is_not_republished() {
4610        let state = RefreshServerState {
4611            instruments_payload: Arc::new(tokio::sync::Mutex::new(test_payload(
4612                "http_get_instruments_swap.json",
4613            ))),
4614            ..RefreshServerState::default()
4615        };
4616        let addr = start_refresh_server(state).await;
4617        let http = refresh_http_client(addr);
4618        let config = OKXDataClientConfig::builder()
4619            .instrument_types(vec![OKXInstrumentType::Swap])
4620            .build();
4621        let instruments_by_symbol = Arc::new(AtomicMap::new());
4622        let update_lock = InstrumentUpdateLock::default();
4623        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
4624
4625        reconcile_instruments(
4626            &http,
4627            &config,
4628            &instruments_by_symbol,
4629            &update_lock,
4630            None,
4631            None,
4632            &sender.clone().into(),
4633        )
4634        .await
4635        .expect("reconcile");
4636        assert_eq!(instrument_events(&mut receiver).len(), 3);
4637
4638        // Feed the same venue definition back through the WebSocket handler:
4639        // cross-source parsing must compare equal, so nothing is republished
4640        let rest_item = test_payload("http_get_instruments_swap.json")["data"][2].clone();
4641        assert_eq!(rest_item["instId"], json!("BTC-USDT-SWAP"));
4642        handle_instruments_message(
4643            &sender.clone().into(),
4644            &instruments_by_symbol,
4645            &http,
4646            &OKXDataClientConfig::default(),
4647            None,
4648            None,
4649            ws_instruments_message(rest_item),
4650        );
4651
4652        match receiver.try_recv().expect("status event") {
4653            DataEvent::Data(Data::InstrumentStatus(status)) => {
4654                assert_eq!(
4655                    status.instrument_id,
4656                    InstrumentId::from("BTC-USDT-SWAP.OKX")
4657                );
4658            }
4659            other => panic!("Expected DataEvent::Data(Data::InstrumentStatus(...)), was {other:?}"),
4660        }
4661        assert!(
4662            receiver.try_recv().is_err(),
4663            "a definition identical to the REST fetch must not be republished"
4664        );
4665    }
4666
4667    #[rstest]
4668    fn definitions_match_ignores_event_timestamps() {
4669        let okx_instrument: OKXInstrument =
4670            serde_json::from_value(swap_definition("0.1")).expect("valid OKXInstrument");
4671        let first = parse_instrument_any(&okx_instrument, None, None, UnixNanos::from(1u64))
4672            .expect("parse")
4673            .expect("instrument");
4674        let second = parse_instrument_any(&okx_instrument, None, None, UnixNanos::from(2u64))
4675            .expect("parse")
4676            .expect("instrument");
4677
4678        assert!(instrument_definitions_match(&first, &second));
4679    }
4680
4681    #[rstest]
4682    fn definitions_match_detects_increment_changes() {
4683        let mut pair = currency_pair_btcusdt();
4684        let mut changed = pair.clone();
4685        changed.price_increment = Price::from("0.5");
4686        pair.ts_event = UnixNanos::from(1u64);
4687        changed.ts_event = UnixNanos::from(2u64);
4688
4689        assert!(!instrument_definitions_match(
4690            &InstrumentAny::CurrencyPair(pair),
4691            &InstrumentAny::CurrencyPair(changed),
4692        ));
4693    }
4694
4695    #[rstest]
4696    fn definitions_match_detects_info_changes() {
4697        let pair = currency_pair_btcusdt();
4698        let mut changed = pair.clone();
4699        let info = Params::new([("okx_rpi_min_level".to_string(), json!(5))].into());
4700        changed.info = Some(info);
4701
4702        assert!(!instrument_definitions_match(
4703            &InstrumentAny::CurrencyPair(pair),
4704            &InstrumentAny::CurrencyPair(changed),
4705        ));
4706    }
4707
4708    #[rstest]
4709    fn definitions_match_detects_id_changes() {
4710        let pair = currency_pair_btcusdt();
4711        let mut other = pair.clone();
4712        other.id = InstrumentId::from("ETH-USDT.OKX");
4713
4714        assert!(!instrument_definitions_match(
4715            &InstrumentAny::CurrencyPair(pair),
4716            &InstrumentAny::CurrencyPair(other),
4717        ));
4718    }
4719
4720    #[derive(Clone, Default)]
4721    struct RefreshServerState {
4722        instruments_payload: Arc<tokio::sync::Mutex<Value>>,
4723        spreads_payload: Arc<tokio::sync::Mutex<Value>>,
4724        instrument_queries: Arc<tokio::sync::Mutex<Vec<HashMap<String, String>>>>,
4725        spread_queries: Arc<tokio::sync::Mutex<Vec<HashMap<String, String>>>>,
4726        fail_instruments: bool,
4727        gate_instruments: Option<Arc<tokio::sync::Semaphore>>,
4728    }
4729
4730    async fn start_refresh_server(state: RefreshServerState) -> SocketAddr {
4731        let instruments_state = state.clone();
4732        let spreads_state = state;
4733
4734        let router =
4735            Router::new()
4736                .route(
4737                    "/api/v5/public/instruments",
4738                    get(move |Query(params): Query<HashMap<String, String>>| {
4739                        let state = instruments_state.clone();
4740                        async move {
4741                            state.instrument_queries.lock().await.push(params.clone());
4742
4743                            if let Some(gate) = &state.gate_instruments {
4744                                gate.acquire()
4745                                    .await
4746                                    .expect("instruments gate open")
4747                                    .forget();
4748                            }
4749
4750                            if state.fail_instruments {
4751                                return (
4752                                    axum::http::StatusCode::INTERNAL_SERVER_ERROR,
4753                                    Json(json!({
4754                                        "code": "50000",
4755                                        "msg": "instruments endpoint unavailable",
4756                                        "data": []
4757                                    })),
4758                                );
4759                            }
4760
4761                            let family = params.get("instFamily").cloned();
4762                            let mut payload = state.instruments_payload.lock().await.clone();
4763
4764                            if let Some(family) = family
4765                                && let Some(data) =
4766                                    payload.get_mut("data").and_then(Value::as_array_mut)
4767                            {
4768                                data.retain(|item| {
4769                                    item.get("instFamily").and_then(Value::as_str)
4770                                        == Some(family.as_str())
4771                                });
4772                            }
4773                            (axum::http::StatusCode::OK, Json(payload))
4774                        }
4775                    }),
4776                )
4777                .route(
4778                    "/api/v5/sprd/spreads",
4779                    get(move |Query(params): Query<HashMap<String, String>>| {
4780                        let state = spreads_state.clone();
4781                        async move {
4782                            state.spread_queries.lock().await.push(params);
4783                            Json(state.spreads_payload.lock().await.clone())
4784                        }
4785                    }),
4786                )
4787                .route(
4788                    "/ws/public",
4789                    get(|ws: axum::extract::ws::WebSocketUpgrade| async move {
4790                        ws.on_upgrade(drain_ws)
4791                    }),
4792                )
4793                .route(
4794                    "/ws/business",
4795                    get(|ws: axum::extract::ws::WebSocketUpgrade| async move {
4796                        ws.on_upgrade(drain_ws)
4797                    }),
4798                );
4799
4800        let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
4801            .await
4802            .expect("bind");
4803        let addr = listener.local_addr().expect("local_addr");
4804        tokio::spawn(async move { axum::serve(listener, router).await.expect("serve") });
4805        addr
4806    }
4807
4808    async fn drain_ws(mut socket: axum::extract::ws::WebSocket) {
4809        while socket.next().await.is_some() {}
4810    }
4811
4812    fn test_payload(filename: &str) -> Value {
4813        serde_json::from_str(&load_test_json(filename)).expect("valid json fixture")
4814    }
4815
4816    fn refresh_http_client(addr: SocketAddr) -> OKXHttpClient {
4817        OKXHttpClient::new(
4818            Some(format!("http://{addr}")),
4819            5,
4820            0,
4821            1,
4822            1,
4823            OKXEnvironment::Live,
4824            None,
4825        )
4826        .expect("http client")
4827    }
4828
4829    fn spot_refresh_state() -> RefreshServerState {
4830        RefreshServerState {
4831            instruments_payload: Arc::new(tokio::sync::Mutex::new(test_payload(
4832                "http_get_instruments_spot.json",
4833            ))),
4834            ..RefreshServerState::default()
4835        }
4836    }
4837
4838    fn instrument_events(
4839        receiver: &mut tokio::sync::mpsc::UnboundedReceiver<DataEvent>,
4840    ) -> Vec<InstrumentAny> {
4841        let mut events = Vec::new();
4842        while let Ok(DataEvent::Data(Data::Instrument(instrument))) = receiver.try_recv() {
4843            events.push(*instrument);
4844        }
4845        events
4846    }
4847
4848    #[tokio::test]
4849    async fn reconcile_publishes_only_new_or_changed_and_retains_missing() {
4850        let state = spot_refresh_state();
4851        let addr = start_refresh_server(state.clone()).await;
4852        let http = refresh_http_client(addr);
4853        let config = OKXDataClientConfig::default();
4854        let instruments_by_symbol = Arc::new(AtomicMap::new());
4855        let update_lock = InstrumentUpdateLock::default();
4856        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
4857
4858        let summary = reconcile_instruments(
4859            &http,
4860            &config,
4861            &instruments_by_symbol,
4862            &update_lock,
4863            None,
4864            None,
4865            &sender.clone().into(),
4866        )
4867        .await
4868        .expect("initial reconcile");
4869        assert_eq!(summary.fetched, 5);
4870        assert_eq!(summary.changed, 5);
4871        assert_eq!(summary.missing, 0);
4872        assert_eq!(instrument_events(&mut receiver).len(), 5);
4873        assert_eq!(instruments_by_symbol.load().len(), 5);
4874
4875        let summary = reconcile_instruments(
4876            &http,
4877            &config,
4878            &instruments_by_symbol,
4879            &update_lock,
4880            None,
4881            None,
4882            &sender.clone().into(),
4883        )
4884        .await
4885        .expect("unchanged reconcile");
4886        assert_eq!(summary.fetched, 5);
4887        assert_eq!(summary.changed, 0);
4888        assert_eq!(summary.missing, 0);
4889        assert!(
4890            instrument_events(&mut receiver).is_empty(),
4891            "unchanged definitions must not be republished"
4892        );
4893
4894        {
4895            let mut payload = state.instruments_payload.lock().await;
4896            payload["data"][0]["tickSz"] = json!("0.5");
4897        }
4898        let summary = reconcile_instruments(
4899            &http,
4900            &config,
4901            &instruments_by_symbol,
4902            &update_lock,
4903            None,
4904            None,
4905            &sender.clone().into(),
4906        )
4907        .await
4908        .expect("changed reconcile");
4909        assert_eq!(summary.changed, 1);
4910        let events = instrument_events(&mut receiver);
4911        assert_eq!(events.len(), 1);
4912        assert_eq!(events[0].id(), InstrumentId::from("BTC-USD.OKX"));
4913        assert_eq!(events[0].price_increment(), Price::from("0.5"));
4914
4915        {
4916            let mut payload = state.instruments_payload.lock().await;
4917            let mut new_instrument = payload["data"][0].clone();
4918            new_instrument["instId"] = json!("ETH-USDT");
4919            new_instrument["baseCcy"] = json!("ETH");
4920            new_instrument["quoteCcy"] = json!("USDT");
4921            payload["data"]
4922                .as_array_mut()
4923                .expect("data array")
4924                .push(new_instrument);
4925        }
4926        let summary = reconcile_instruments(
4927            &http,
4928            &config,
4929            &instruments_by_symbol,
4930            &update_lock,
4931            None,
4932            None,
4933            &sender.clone().into(),
4934        )
4935        .await
4936        .expect("new listing reconcile");
4937        assert_eq!(summary.fetched, 6);
4938        assert_eq!(summary.changed, 1);
4939        let events = instrument_events(&mut receiver);
4940        assert_eq!(events.len(), 1);
4941        assert_eq!(events[0].id(), InstrumentId::from("ETH-USDT.OKX"));
4942        assert_eq!(instruments_by_symbol.load().len(), 6);
4943
4944        {
4945            let mut payload = state.instruments_payload.lock().await;
4946            payload["data"]
4947                .as_array_mut()
4948                .expect("data array")
4949                .remove(0);
4950        }
4951        let summary = reconcile_instruments(
4952            &http,
4953            &config,
4954            &instruments_by_symbol,
4955            &update_lock,
4956            None,
4957            None,
4958            &sender.clone().into(),
4959        )
4960        .await
4961        .expect("removal reconcile");
4962        assert_eq!(summary.fetched, 5);
4963        assert_eq!(summary.changed, 0);
4964        assert_eq!(summary.missing, 1);
4965        assert!(
4966            instrument_events(&mut receiver).is_empty(),
4967            "removed instruments must not publish events"
4968        );
4969        assert!(
4970            instruments_by_symbol
4971                .get_cloned(&Ustr::from("BTC-USD"))
4972                .is_some(),
4973            "removed instruments are retained in the cache"
4974        );
4975    }
4976
4977    #[tokio::test]
4978    async fn reconcile_surfaces_fetch_errors_without_publishing() {
4979        let state = RefreshServerState {
4980            fail_instruments: true,
4981            ..spot_refresh_state()
4982        };
4983        let addr = start_refresh_server(state).await;
4984        let http = refresh_http_client(addr);
4985        let config = OKXDataClientConfig::default();
4986        let instruments_by_symbol = Arc::new(AtomicMap::new());
4987        let update_lock = InstrumentUpdateLock::default();
4988        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
4989
4990        let result = reconcile_instruments(
4991            &http,
4992            &config,
4993            &instruments_by_symbol,
4994            &update_lock,
4995            None,
4996            None,
4997            &sender.clone().into(),
4998        )
4999        .await;
5000
5001        assert!(result.is_err(), "fetch failure must surface as an error");
5002        assert!(instruments_by_symbol.load().is_empty());
5003        assert!(
5004            receiver.try_recv().is_err(),
5005            "a failed reconcile must not publish events"
5006        );
5007    }
5008
5009    #[tokio::test]
5010    async fn reconcile_requests_each_configured_family() {
5011        let state = RefreshServerState {
5012            instruments_payload: Arc::new(tokio::sync::Mutex::new(test_payload(
5013                "http_get_instruments_swap.json",
5014            ))),
5015            ..RefreshServerState::default()
5016        };
5017        let addr = start_refresh_server(state.clone()).await;
5018        let http = refresh_http_client(addr);
5019        let config = OKXDataClientConfig::builder()
5020            .instrument_types(vec![OKXInstrumentType::Swap])
5021            .instrument_families(vec!["BTC-USD".to_string(), "BTC-USDT".to_string()])
5022            .build();
5023        let instruments_by_symbol = Arc::new(AtomicMap::new());
5024        let update_lock = InstrumentUpdateLock::default();
5025        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
5026
5027        let summary = reconcile_instruments(
5028            &http,
5029            &config,
5030            &instruments_by_symbol,
5031            &update_lock,
5032            None,
5033            None,
5034            &sender.clone().into(),
5035        )
5036        .await
5037        .expect("reconcile");
5038
5039        let queries = state.instrument_queries.lock().await;
5040        let families: Vec<Option<String>> = queries
5041            .iter()
5042            .map(|query| query.get("instFamily").cloned())
5043            .collect();
5044        assert_eq!(queries.len(), 2);
5045        assert!(families.contains(&Some("BTC-USD".to_string())));
5046        assert!(families.contains(&Some("BTC-USDT".to_string())));
5047        drop(queries);
5048
5049        assert_eq!(summary.fetched, 2);
5050        assert_eq!(summary.changed, 2);
5051        let ids: Vec<InstrumentId> = instrument_events(&mut receiver)
5052            .iter()
5053            .map(Instrument::id)
5054            .collect();
5055        assert!(ids.contains(&InstrumentId::from("BTC-USD-SWAP.OKX")));
5056        assert!(ids.contains(&InstrumentId::from("BTC-USDT-SWAP.OKX")));
5057    }
5058
5059    #[rstest]
5060    #[case::inverse_keeps_inverse_only(vec![OKXContractType::Inverse], 1, "BTC-USD-SWAP.OKX")]
5061    #[case::linear_keeps_linear_only(vec![OKXContractType::Linear], 2, "BTC-USDT-SWAP.OKX")]
5062    #[tokio::test]
5063    async fn reconcile_applies_contract_type_filter(
5064        #[case] filter: Vec<OKXContractType>,
5065        #[case] expected_count: usize,
5066        #[case] expected_id: &str,
5067    ) {
5068        let state = RefreshServerState {
5069            instruments_payload: Arc::new(tokio::sync::Mutex::new(test_payload(
5070                "http_get_instruments_swap.json",
5071            ))),
5072            ..RefreshServerState::default()
5073        };
5074        let addr = start_refresh_server(state).await;
5075        let http = refresh_http_client(addr);
5076        let config = OKXDataClientConfig::builder()
5077            .instrument_types(vec![OKXInstrumentType::Swap])
5078            .contract_types(filter)
5079            .build();
5080        let instruments_by_symbol = Arc::new(AtomicMap::new());
5081        let update_lock = InstrumentUpdateLock::default();
5082        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
5083
5084        let summary = reconcile_instruments(
5085            &http,
5086            &config,
5087            &instruments_by_symbol,
5088            &update_lock,
5089            None,
5090            None,
5091            &sender.clone().into(),
5092        )
5093        .await
5094        .expect("reconcile");
5095
5096        assert_eq!(summary.fetched, expected_count);
5097        assert_eq!(summary.changed, expected_count);
5098        let events = instrument_events(&mut receiver);
5099        assert_eq!(events.len(), expected_count);
5100        assert!(
5101            events
5102                .iter()
5103                .any(|i| i.id() == InstrumentId::from(expected_id)),
5104            "expected {expected_id} in filtered results"
5105        );
5106    }
5107
5108    #[tokio::test]
5109    async fn reconcile_includes_spreads_when_load_spreads_enabled() {
5110        let state = RefreshServerState {
5111            instruments_payload: Arc::new(tokio::sync::Mutex::new(test_payload(
5112                "http_get_instruments_spot.json",
5113            ))),
5114            spreads_payload: Arc::new(tokio::sync::Mutex::new(test_payload(
5115                "http_get_spreads.json",
5116            ))),
5117            ..RefreshServerState::default()
5118        };
5119        let addr = start_refresh_server(state.clone()).await;
5120        let http = refresh_http_client(addr);
5121        let config = OKXDataClientConfig::builder().load_spreads(true).build();
5122        let instruments_by_symbol = Arc::new(AtomicMap::new());
5123        let update_lock = InstrumentUpdateLock::default();
5124        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
5125
5126        let summary = reconcile_instruments(
5127            &http,
5128            &config,
5129            &instruments_by_symbol,
5130            &update_lock,
5131            None,
5132            None,
5133            &sender.clone().into(),
5134        )
5135        .await
5136        .expect("reconcile");
5137
5138        assert_eq!(state.spread_queries.lock().await.len(), 1);
5139        assert_eq!(summary.fetched, 7);
5140        assert_eq!(summary.changed, 7);
5141        let ids: Vec<InstrumentId> = instrument_events(&mut receiver)
5142            .iter()
5143            .map(Instrument::id)
5144            .collect();
5145        assert!(ids.contains(&InstrumentId::from("ETH-USD-SWAP_ETH-USD-231229.OKX")));
5146        assert!(ids.contains(&InstrumentId::from("BTC-USDT_BTC-USDT-SWAP.OKX")));
5147    }
5148
5149    #[tokio::test]
5150    async fn reconcile_updates_all_caches_before_publishing() {
5151        let state = spot_refresh_state();
5152        let addr = start_refresh_server(state).await;
5153        let http = refresh_http_client(addr);
5154        let config = OKXDataClientConfig::default();
5155        let instruments_by_symbol = Arc::new(AtomicMap::new());
5156        let update_lock = Arc::new(InstrumentUpdateLock::default());
5157        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
5158        let ws = offline_ws_client();
5159        let ws_business = offline_ws_client();
5160
5161        let instruments_task = instruments_by_symbol.clone();
5162        let update_lock_task = update_lock.clone();
5163        let http_task = http.clone();
5164        let ws_task = ws.clone();
5165        let ws_business_task = ws_business.clone();
5166
5167        let reconcile = tokio::spawn(async move {
5168            reconcile_instruments(
5169                &http_task,
5170                &config,
5171                &instruments_task,
5172                &update_lock_task,
5173                Some(&ws_task),
5174                Some(&ws_business_task),
5175                &sender.clone().into(),
5176            )
5177            .await
5178        });
5179
5180        let event = receiver.recv().await.expect("instrument event");
5181
5182        let DataEvent::Data(Data::Instrument(instrument)) = event else {
5183            panic!("Expected DataEvent::Data(Data::Instrument(...)), was {event:?}");
5184        };
5185
5186        assert!(
5187            instruments_by_symbol
5188                .load()
5189                .contains_key(&instrument.symbol().inner()),
5190            "data client cache must be updated before publishing"
5191        );
5192        assert!(
5193            http.get_instrument(&instrument.symbol().inner()).is_some(),
5194            "HTTP client cache must be updated before publishing"
5195        );
5196        assert!(
5197            ws.instruments_snapshot()
5198                .contains_key(&instrument.symbol().inner()),
5199            "public WebSocket cache must be updated before publishing"
5200        );
5201        assert!(
5202            ws_business
5203                .instruments_snapshot()
5204                .contains_key(&instrument.symbol().inner()),
5205            "business WebSocket cache must be updated before publishing"
5206        );
5207        reconcile.await.expect("reconcile task").expect("reconcile");
5208    }
5209
5210    #[tokio::test]
5211    async fn reconcile_skips_publish_when_cache_changes_during_fetch() {
5212        let gate = Arc::new(tokio::sync::Semaphore::new(0));
5213        let state = RefreshServerState {
5214            gate_instruments: Some(gate.clone()),
5215            ..spot_refresh_state()
5216        };
5217        let addr = start_refresh_server(state.clone()).await;
5218        let http = refresh_http_client(addr);
5219        let config = OKXDataClientConfig::default();
5220        let instruments_by_symbol = Arc::new(AtomicMap::new());
5221        let update_lock = Arc::new(InstrumentUpdateLock::default());
5222        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
5223
5224        gate.add_permits(1);
5225        let summary = reconcile_instruments(
5226            &http,
5227            &config,
5228            &instruments_by_symbol,
5229            &update_lock,
5230            None,
5231            None,
5232            &sender.clone().into(),
5233        )
5234        .await
5235        .expect("seed reconcile");
5236        assert_eq!(summary.changed, 5);
5237        assert_eq!(instrument_events(&mut receiver).len(), 5);
5238
5239        let reconcile = {
5240            let http = http.clone();
5241            let instruments_by_symbol = instruments_by_symbol.clone();
5242            let update_lock = update_lock.clone();
5243            let sender = sender.clone();
5244
5245            tokio::spawn(async move {
5246                reconcile_instruments(
5247                    &http,
5248                    &config,
5249                    &instruments_by_symbol,
5250                    &update_lock,
5251                    None,
5252                    None,
5253                    &sender.clone().into(),
5254                )
5255                .await
5256            })
5257        };
5258
5259        let deadline = Instant::now() + Duration::from_secs(5);
5260        while state.instrument_queries.lock().await.len() < 2 {
5261            assert!(Instant::now() < deadline, "refresh fetch not in flight");
5262            tokio::time::sleep(Duration::from_millis(10)).await;
5263        }
5264
5265        // A concurrent update lands while the refresh fetch is in flight
5266        let mut v2_item = test_payload("http_get_instruments_spot.json")["data"][0].clone();
5267        v2_item["tickSz"] = json!("0.5");
5268        let v2: OKXInstrument = serde_json::from_value(v2_item).expect("valid OKXInstrument");
5269        let v2 = parse_instrument_any(&v2, None, None, UnixNanos::from(1u64))
5270            .expect("parse")
5271            .expect("instrument");
5272        {
5273            let _guard = update_lock.mutex.lock();
5274            publish_instrument_updates(
5275                std::slice::from_ref(&v2),
5276                &instruments_by_symbol,
5277                &http,
5278                None,
5279                None,
5280                &update_lock,
5281                &sender.clone().into(),
5282            );
5283        }
5284
5285        match receiver.try_recv().expect("concurrent update event") {
5286            DataEvent::Data(Data::Instrument(instrument)) => {
5287                assert_eq!(instrument.price_increment(), Price::from("0.5"));
5288            }
5289            other => panic!("Expected DataEvent::Data(Data::Instrument(...)), was {other:?}"),
5290        }
5291
5292        gate.add_permits(1);
5293        let summary = reconcile.await.expect("reconcile task").expect("reconcile");
5294        assert_eq!(
5295            summary.changed, 0,
5296            "a pass whose snapshot went stale mid-fetch must skip publishing"
5297        );
5298        assert!(
5299            instrument_events(&mut receiver).is_empty(),
5300            "the stale pass must not republish the older definition"
5301        );
5302        let cached = instruments_by_symbol
5303            .get_cloned(&Ustr::from("BTC-USD"))
5304            .expect("instrument cached");
5305        assert_eq!(
5306            cached.price_increment(),
5307            Price::from("0.5"),
5308            "the instrument cache keeps the fresher concurrent definition"
5309        );
5310        assert_eq!(
5311            http.get_instrument(&Ustr::from("BTC-USD"))
5312                .map(|instrument| instrument.price_increment()),
5313            Some(Price::from("0.5")),
5314            "the HTTP cache keeps the fresher concurrent definition"
5315        );
5316    }
5317
5318    #[rstest]
5319    #[case::reset(DataTaskBoundary::Reset)]
5320    #[case::dispose(DataTaskBoundary::Dispose)]
5321    #[case::repeated_stop(DataTaskBoundary::RepeatedStop)]
5322    #[tokio::test]
5323    async fn lifecycle_boundary_terminates_owned_data_task(#[case] boundary: DataTaskBoundary) {
5324        let (sender, _receiver) = tokio::sync::mpsc::unbounded_channel();
5325        replace_data_event_sender(sender);
5326        let mut client = OKXDataClient::new(*OKX_CLIENT_ID, OKXDataClientConfig::default())
5327            .expect("data client");
5328
5329        if matches!(boundary, DataTaskBoundary::RepeatedStop) {
5330            client.stop().expect("initial stop");
5331        }
5332
5333        let (drop_tx, drop_rx) = tokio::sync::oneshot::channel();
5334        let signal = DropSignal(Some(drop_tx));
5335        client.spawn_ws(
5336            async move {
5337                let _signal = signal;
5338                std::future::pending::<anyhow::Result<()>>().await
5339            },
5340            "pending lifecycle task",
5341        );
5342
5343        match boundary {
5344            DataTaskBoundary::Reset => client.reset().expect("reset"),
5345            DataTaskBoundary::Dispose => client.dispose().expect("dispose"),
5346            DataTaskBoundary::RepeatedStop => client.stop().expect("repeated stop"),
5347        }
5348
5349        tokio::time::timeout(Duration::from_secs(1), drop_rx)
5350            .await
5351            .expect("lifecycle boundary must drop the owned task")
5352            .expect("drop signal");
5353        terminate_tasks(&client.tasks, "test data client")
5354            .await
5355            .expect("data task terminated");
5356        assert!(client.tasks.is_empty());
5357    }
5358
5359    #[tokio::test]
5360    async fn reset_prevents_in_flight_request_from_publishing() {
5361        let gate = Arc::new(tokio::sync::Semaphore::new(0));
5362        let state = RefreshServerState {
5363            gate_instruments: Some(Arc::clone(&gate)),
5364            ..spot_refresh_state()
5365        };
5366        let addr = start_refresh_server(state.clone()).await;
5367        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
5368        replace_data_event_sender(sender);
5369        let config = OKXDataClientConfig {
5370            instrument_types: vec![OKXInstrumentType::Spot],
5371            base_url_http: Some(format!("http://{addr}")),
5372            http_timeout_secs: 5,
5373            max_retries: 0,
5374            retry_delay_initial_ms: 1,
5375            retry_delay_max_ms: 1,
5376            ..OKXDataClientConfig::default()
5377        };
5378        let mut client = OKXDataClient::new(*OKX_CLIENT_ID, config).expect("data client");
5379        let request = RequestInstruments::new(
5380            None,
5381            None,
5382            Some(*OKX_CLIENT_ID),
5383            None,
5384            UUID4::new(),
5385            UnixNanos::default(),
5386            None,
5387        );
5388
5389        client
5390            .request_instruments(request)
5391            .expect("request instruments");
5392        wait_until_async(
5393            || {
5394                let state = state.clone();
5395                async move { !state.instrument_queries.lock().await.is_empty() }
5396            },
5397            Duration::from_secs(1),
5398        )
5399        .await;
5400
5401        client.reset().expect("reset");
5402        wait_until_async(
5403            || async { client.tasks.all_finished() },
5404            Duration::from_secs(1),
5405        )
5406        .await;
5407        gate.add_permits(1);
5408
5409        assert!(client.instruments_by_symbol.load().is_empty());
5410        assert!(matches!(
5411            receiver.try_recv(),
5412            Err(tokio::sync::mpsc::error::TryRecvError::Empty)
5413        ));
5414        terminate_tasks(&client.tasks, "test data client")
5415            .await
5416            .expect("data task terminated");
5417    }
5418
5419    #[tokio::test]
5420    async fn reconnect_does_not_leak_refresh_tasks() {
5421        let state = spot_refresh_state();
5422        let addr = start_refresh_server(state).await;
5423        let (sender, _receiver) = tokio::sync::mpsc::unbounded_channel();
5424        replace_data_event_sender(sender);
5425        let config = OKXDataClientConfig {
5426            instrument_types: vec![OKXInstrumentType::Spot],
5427            base_url_http: Some(format!("http://{addr}")),
5428            base_url_ws_public: Some(format!("ws://{addr}/ws/public")),
5429            base_url_ws_business: Some(format!("ws://{addr}/ws/business")),
5430            environment: OKXEnvironment::Live,
5431            http_timeout_secs: 5,
5432            max_retries: 0,
5433            retry_delay_initial_ms: 1,
5434            retry_delay_max_ms: 1,
5435            book_stale_check_interval_secs: 0,
5436            update_instruments_interval_mins: 60,
5437            ..OKXDataClientConfig::default()
5438        };
5439        let mut client = OKXDataClient::new(*OKX_CLIENT_ID, config).expect("data client");
5440
5441        for cycle in 1..=2 {
5442            client.connect().await.expect("connect");
5443            assert_eq!(
5444                client.tasks.len(),
5445                3,
5446                "cycle {cycle}: two stream tasks and one refresh task"
5447            );
5448            client.disconnect().await.expect("disconnect");
5449            assert!(
5450                client.tasks.is_empty(),
5451                "cycle {cycle}: teardown must join every task"
5452            );
5453        }
5454
5455        client.connect().await.expect("connect");
5456        client.connect().await.expect("repeated connect is a no-op");
5457        assert_eq!(client.tasks.len(), 3);
5458        client.disconnect().await.expect("disconnect");
5459    }
5460
5461    #[tokio::test]
5462    async fn reset_drains_old_generation_before_reconnect() {
5463        let state = spot_refresh_state();
5464        let addr = start_refresh_server(state).await;
5465        let (sender, _receiver) = tokio::sync::mpsc::unbounded_channel();
5466        replace_data_event_sender(sender);
5467        let config = OKXDataClientConfig {
5468            instrument_types: vec![OKXInstrumentType::Spot],
5469            base_url_http: Some(format!("http://{addr}")),
5470            base_url_ws_public: Some(format!("ws://{addr}/ws/public")),
5471            base_url_ws_business: Some(format!("ws://{addr}/ws/business")),
5472            environment: OKXEnvironment::Live,
5473            http_timeout_secs: 5,
5474            max_retries: 0,
5475            retry_delay_initial_ms: 1,
5476            retry_delay_max_ms: 1,
5477            book_stale_check_interval_secs: 0,
5478            update_instruments_interval_mins: 60,
5479            ..OKXDataClientConfig::default()
5480        };
5481        let mut client = OKXDataClient::new(*OKX_CLIENT_ID, config).expect("data client");
5482
5483        client.connect().await.expect("initial connect");
5484        client.reset().expect("reset");
5485        client.connect().await.expect("reconnect after reset");
5486
5487        assert_eq!(client.tasks.len(), 3);
5488        assert!(!client.tasks.all_finished());
5489        client.disconnect().await.expect("disconnect");
5490    }
5491
5492    #[tokio::test]
5493    async fn reconnect_does_not_republish_unchanged_instruments() {
5494        let state = spot_refresh_state();
5495        let addr = start_refresh_server(state.clone()).await;
5496        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
5497        replace_data_event_sender(sender);
5498        let config = OKXDataClientConfig {
5499            instrument_types: vec![OKXInstrumentType::Spot],
5500            base_url_http: Some(format!("http://{addr}")),
5501            base_url_ws_public: Some(format!("ws://{addr}/ws/public")),
5502            base_url_ws_business: Some(format!("ws://{addr}/ws/business")),
5503            environment: OKXEnvironment::Live,
5504            http_timeout_secs: 5,
5505            max_retries: 0,
5506            retry_delay_initial_ms: 1,
5507            retry_delay_max_ms: 1,
5508            book_stale_check_interval_secs: 0,
5509            update_instruments_interval_mins: 60,
5510            ..OKXDataClientConfig::default()
5511        };
5512        let mut client = OKXDataClient::new(*OKX_CLIENT_ID, config).expect("data client");
5513
5514        client.connect().await.expect("first connect");
5515        assert_eq!(
5516            instrument_events(&mut receiver).len(),
5517            5,
5518            "first connect publishes the full cache"
5519        );
5520        client.disconnect().await.expect("disconnect");
5521
5522        client.connect().await.expect("reconnect");
5523        assert!(
5524            instrument_events(&mut receiver).is_empty(),
5525            "reconnect must not republish unchanged instruments"
5526        );
5527        client.disconnect().await.expect("disconnect");
5528
5529        {
5530            let mut payload = state.instruments_payload.lock().await;
5531            payload["data"][0]["tickSz"] = json!("0.5");
5532        }
5533        client.connect().await.expect("third connect");
5534        let events = instrument_events(&mut receiver);
5535        assert_eq!(
5536            events.len(),
5537            1,
5538            "reconnect publishes only changed definitions"
5539        );
5540        assert_eq!(events[0].id(), InstrumentId::from("BTC-USD.OKX"));
5541        client.disconnect().await.expect("disconnect");
5542    }
5543
5544    #[tokio::test]
5545    async fn stop_cancels_refresh_task() {
5546        let state = spot_refresh_state();
5547        let addr = start_refresh_server(state).await;
5548        let (sender, _receiver) = tokio::sync::mpsc::unbounded_channel();
5549        replace_data_event_sender(sender);
5550        let config = OKXDataClientConfig {
5551            instrument_types: vec![OKXInstrumentType::Spot],
5552            base_url_http: Some(format!("http://{addr}")),
5553            base_url_ws_public: Some(format!("ws://{addr}/ws/public")),
5554            base_url_ws_business: Some(format!("ws://{addr}/ws/business")),
5555            environment: OKXEnvironment::Live,
5556            http_timeout_secs: 5,
5557            max_retries: 0,
5558            retry_delay_initial_ms: 1,
5559            retry_delay_max_ms: 1,
5560            book_stale_check_interval_secs: 0,
5561            update_instruments_interval_mins: 60,
5562            ..OKXDataClientConfig::default()
5563        };
5564        let mut client = OKXDataClient::new(*OKX_CLIENT_ID, config).expect("data client");
5565
5566        client.connect().await.expect("connect");
5567        assert_eq!(client.tasks.len(), 3);
5568
5569        client.stop().expect("stop");
5570        terminate_tasks(&client.tasks, "test data client")
5571            .await
5572            .expect("stop must cancel every spawned task");
5573
5574        client.disconnect().await.expect("disconnect");
5575    }
5576
5577    #[tokio::test]
5578    async fn zero_interval_disables_refresh_on_connect() {
5579        let addr = start_refresh_server(spot_refresh_state()).await;
5580        let (sender, _receiver) = tokio::sync::mpsc::unbounded_channel();
5581        replace_data_event_sender(sender);
5582        let config = OKXDataClientConfig {
5583            instrument_types: vec![OKXInstrumentType::Spot],
5584            base_url_http: Some(format!("http://{addr}")),
5585            base_url_ws_public: Some(format!("ws://{addr}/ws/public")),
5586            base_url_ws_business: Some(format!("ws://{addr}/ws/business")),
5587            environment: OKXEnvironment::Live,
5588            http_timeout_secs: 5,
5589            max_retries: 0,
5590            retry_delay_initial_ms: 1,
5591            retry_delay_max_ms: 1,
5592            book_stale_check_interval_secs: 0,
5593            update_instruments_interval_mins: 0,
5594            ..OKXDataClientConfig::default()
5595        };
5596        let mut client = OKXDataClient::new(*OKX_CLIENT_ID, config).expect("data client");
5597
5598        client.connect().await.expect("connect");
5599        assert_eq!(
5600            client.tasks.len(),
5601            2,
5602            "only the two stream tasks run when refresh is disabled"
5603        );
5604
5605        client.disconnect().await.expect("disconnect");
5606    }
5607
5608    #[rstest]
5609    #[case::complete(OKXHistoryCoverage::Complete)]
5610    #[case::truncated(OKXHistoryCoverage::Truncated)]
5611    #[case::unverified(OKXHistoryCoverage::Unverified)]
5612    fn test_history_event_follows_coverage(#[case] coverage: OKXHistoryCoverage) {
5613        let request_id = UUID4::new();
5614        let response = DataResponse::Trades(TradesResponse::new(
5615            request_id,
5616            *OKX_CLIENT_ID,
5617            InstrumentId::from("BTC-USD.OKX"),
5618            Vec::new(),
5619            None,
5620            None,
5621            UnixNanos::default(),
5622            None,
5623        ));
5624
5625        match (coverage, history_event(request_id, response, coverage)) {
5626            (OKXHistoryCoverage::Complete, DataEvent::ResponseEnvelope(envelope)) => {
5627                assert!(envelope.completed());
5628                assert!(envelope.response().is_some());
5629            }
5630            (OKXHistoryCoverage::Truncated, DataEvent::RequestFailed(failure)) => {
5631                assert_eq!(failure.request_id, request_id);
5632                assert!(failure.response.is_some());
5633            }
5634            (OKXHistoryCoverage::Unverified, DataEvent::Response(_)) => {}
5635            (coverage, event) => panic!("{coverage:?} gave {event:?}"),
5636        }
5637    }
5638}
5639
5640#[cfg(test)]
5641#[path = "../tests/integration/book_sync.rs"]
5642mod book_sync_tests;