Skip to main content

nautilus_lighter/data/
mod.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 data client for the Lighter adapter.
17
18use std::{
19    sync::{
20        Arc,
21        atomic::{AtomicBool, AtomicU64, Ordering},
22    },
23    time::Duration,
24};
25
26use ahash::AHashMap;
27use anyhow::Context;
28use dashmap::{DashMap, DashSet, mapref::entry::Entry};
29use nautilus_common::{
30    cache::InstrumentLookupError,
31    clients::{DataClient, execute_bar_subscriptions, execute_instrument_subscriptions},
32    live::{runner::get_data_event_sender, sender::EventSender},
33    messages::{
34        DataEvent,
35        data::{
36            BarsResponse, BookResponse, DataResponse, FundingRatesResponse, InstrumentResponse,
37            InstrumentsResponse, RequestBars, RequestBookDepth, RequestBookSnapshot,
38            RequestFundingRates, RequestInstrument, RequestInstruments, RequestQuotes,
39            RequestTrades, SubscribeBars, SubscribeBookDeltas, SubscribeBookDepth,
40            SubscribeFundingRates, SubscribeIndexPrices, SubscribeInstrument,
41            SubscribeInstrumentStatus, SubscribeMarkPrices, SubscribeQuotes, SubscribeTrades,
42            TradesResponse, UnsubscribeBars, UnsubscribeBookDeltas, UnsubscribeBookDepth,
43            UnsubscribeFundingRates, UnsubscribeIndexPrices, UnsubscribeInstrument,
44            UnsubscribeInstrumentStatus, UnsubscribeMarkPrices, UnsubscribeQuotes,
45            UnsubscribeTrades,
46        },
47    },
48};
49use nautilus_core::{
50    AtomicMap, UnixNanos,
51    datetime::datetime_to_unix_nanos,
52    time::{AtomicTime, get_atomic_clock_realtime},
53};
54use nautilus_live::{
55    SocketControlFactory,
56    task::{TaskGroup, TaskGroupGuard, TaskJoinOutcome, TaskSlot, finish_task},
57};
58use nautilus_model::{
59    data::{Data, InstrumentStatus, TradeTick},
60    enums::{BookType, MarketStatusAction},
61    identifiers::{ClientId, InstrumentId, Venue},
62    instruments::{Instrument, InstrumentAny},
63};
64use tokio_util::sync::CancellationToken;
65
66use crate::{
67    common::{
68        consts::DISCONNECT_TIMEOUT,
69        enums::{LighterCandleResolution, LighterMarketStatus},
70        rate_limit::resolve_quota,
71        symbol::MarketRegistry,
72    },
73    config::{LighterDataClientConfig, validate_proxy_url},
74    http::{
75        client::{LighterHttpClient, LighterRawHttpClient},
76        parse::parse_l2_order_book_snapshot,
77        query::LighterOrderBookOrdersQuery,
78    },
79    websocket::{
80        DATA_STREAMS_ENDPOINT, LighterWsError,
81        client::{LighterWebSocketClient, RetainedTaskSlot, TaskRetentionGuard},
82        messages::{LighterMarketSelection, LighterWsChannel, NautilusWsMessage},
83    },
84};
85
86mod limits;
87mod market_stats;
88
89use self::{
90    limits::{clamp_book_snapshot_limit, clamp_recent_trades_limit},
91    market_stats::{
92        MarketStatsKind, MarketStatsSubscription, emit_ws_message as emit_market_stats_ws_message,
93        subscribe_channel as subscribe_market_stats_channel,
94        unsubscribe_channel as unsubscribe_market_stats_channel,
95    },
96};
97
98#[derive(Debug)]
99pub struct LighterDataClient {
100    clock: &'static AtomicTime,
101    client_id: ClientId,
102    config: LighterDataClientConfig,
103    http_client: LighterHttpClient,
104    ws_client: LighterWebSocketClient,
105    registry: Arc<MarketRegistry>,
106    socket_factory: SocketControlFactory,
107    is_connected: AtomicBool,
108    cancellation_token: CancellationToken,
109    tasks: TaskGroup,
110    ws_disconnect_handle: TaskSlot<Result<(), LighterWsError>>,
111    ws_handler_retained: Arc<RetainedTaskSlot>,
112    shutdown_errors: Vec<String>,
113    data_sender: EventSender<DataEvent>,
114    instruments: Arc<AtomicMap<InstrumentId, InstrumentAny>>,
115    instrument_statuses: Arc<DashMap<InstrumentId, LighterMarketStatus>>,
116    instrument_status_subscriptions: Arc<DashSet<InstrumentId>>,
117    market_stats_subscriptions: Arc<DashMap<InstrumentId, MarketStatsSubscription>>,
118    market_stats_subscription_generations: Arc<DashMap<InstrumentId, u64>>,
119    next_market_stats_subscription_generation: AtomicU64,
120}
121
122impl LighterDataClient {
123    /// Creates a new [`LighterDataClient`] instance.
124    ///
125    /// # Errors
126    ///
127    /// Returns an error if the proxy URL is invalid or the HTTP client fails to initialize.
128    pub fn new(client_id: ClientId, config: LighterDataClientConfig) -> anyhow::Result<Self> {
129        validate_proxy_url(config.proxy_url.as_ref())?;
130        let clock = get_atomic_clock_realtime();
131        let data_sender = get_data_event_sender();
132        let venue = config.resolved_venue();
133        let settlement_currency = config.settlement_currency();
134        let socket_factory = SocketControlFactory::new(client_id, Some(venue));
135
136        let registry = Arc::new(MarketRegistry::new_with_venue_and_settlement_currency(
137            venue,
138            settlement_currency,
139        ));
140
141        let raw_http = LighterRawHttpClient::new_with_quotas(
142            config.environment,
143            Some(config.http_url()),
144            config.http_timeout_secs,
145            config
146                .proxy_url
147                .as_ref()
148                .map(|value| value.expose_secret().to_owned()),
149            resolve_quota(config.rest_quota_per_min),
150            None,
151        )
152        .context("failed to construct Lighter raw HTTP client")?;
153
154        let http_client =
155            LighterHttpClient::from_raw_with_registry(raw_http, Arc::clone(&registry));
156
157        let ws_client = Self::create_ws_client(&config, Arc::clone(&registry), &socket_factory);
158
159        let tasks = TaskGroup::new();
160
161        Ok(Self {
162            clock,
163            client_id,
164            config,
165            http_client,
166            ws_client,
167            registry,
168            socket_factory,
169            is_connected: AtomicBool::new(false),
170            cancellation_token: tasks.cancellation_token(),
171            tasks,
172            ws_disconnect_handle: TaskSlot::new(),
173            ws_handler_retained: Arc::new(RetainedTaskSlot::new()),
174            shutdown_errors: Vec::new(),
175            data_sender,
176            instruments: Arc::new(AtomicMap::new()),
177            instrument_statuses: Arc::new(DashMap::new()),
178            instrument_status_subscriptions: Arc::new(DashSet::new()),
179            market_stats_subscriptions: Arc::new(DashMap::new()),
180            market_stats_subscription_generations: Arc::new(DashMap::new()),
181            next_market_stats_subscription_generation: AtomicU64::new(1),
182        })
183    }
184
185    fn venue(&self) -> Venue {
186        self.config.resolved_venue()
187    }
188
189    /// Returns `true` when all credential fields are present in config or the selected environment.
190    ///
191    /// This checks presence without validating credentials. Public data requests do not use them.
192    #[must_use]
193    pub fn has_credentials(&self) -> bool {
194        self.config.has_credentials()
195    }
196
197    fn create_ws_client(
198        config: &LighterDataClientConfig,
199        registry: Arc<MarketRegistry>,
200        socket_factory: &SocketControlFactory,
201    ) -> LighterWebSocketClient {
202        let ws_client = LighterWebSocketClient::new(
203            Some(config.ws_url()),
204            config.environment,
205            registry,
206            config.transport_backend,
207            config.ws_timeout_secs,
208            Duration::from_secs(config.book_snapshot_timeout_secs),
209            config
210                .proxy_url
211                .as_ref()
212                .map(|value| value.expose_secret().to_owned()),
213        );
214
215        ws_client.with_socket_control(socket_factory.control(DATA_STREAMS_ENDPOINT))
216    }
217
218    fn take_ws_client(&mut self) -> LighterWebSocketClient {
219        std::mem::replace(
220            &mut self.ws_client,
221            Self::create_ws_client(
222                &self.config,
223                Arc::clone(&self.registry),
224                &self.socket_factory,
225            ),
226        )
227    }
228
229    fn spawn_ws_disconnect(&mut self) {
230        if self.ws_disconnect_handle.is_some() {
231            return;
232        }
233        self.ws_client.begin_shutdown();
234        let ws_client = self.take_ws_client();
235        let retained = Arc::clone(&self.ws_handler_retained);
236
237        if let Err(e) = self
238            .ws_disconnect_handle
239            .spawn(ws_client.disconnect_with_task_retention(retained))
240        {
241            log::error!("Failed to start Lighter WebSocket disconnect task: {e}");
242        }
243    }
244
245    // Biased select drops an in-flight task on cancellation before it emits a late DataEvent
246    fn spawn_task<F>(&self, fut: F)
247    where
248        F: std::future::Future<Output = ()> + Send + 'static,
249    {
250        let cancellation_token = self.cancellation_token.clone();
251
252        let future = async move {
253            tokio::select! {
254                biased;
255                () = cancellation_token.cancelled() => {}
256                () = fut => {}
257            }
258        };
259
260        if let Err(e) = self.tasks.spawn(future) {
261            log::debug!("Skipping Lighter data task after shutdown began: {e}");
262        }
263    }
264
265    fn abort_tasks(&self) {
266        self.tasks.begin_shutdown();
267    }
268
269    async fn shutdown_tasks(&mut self) -> anyhow::Result<()> {
270        self.tasks.begin_shutdown();
271        if let Err(e) = self
272            .tasks
273            .finish_shutdown(Duration::from_secs(1), DISCONNECT_TIMEOUT)
274            .await
275        {
276            self.shutdown_errors.push(format!("data tasks failed: {e}"));
277        }
278
279        Self::finish_owned_task(
280            &mut self.ws_disconnect_handle,
281            "WebSocket disconnect",
282            &mut self.shutdown_errors,
283        )
284        .await;
285
286        if let Err(e) = self.ws_handler_retained.finish().await {
287            self.shutdown_errors.push(e.to_string());
288        }
289
290        self.take_shutdown_result("Failed to terminate Lighter tasks")
291    }
292
293    fn take_shutdown_result(&mut self, context: &str) -> anyhow::Result<()> {
294        if self.shutdown_errors.is_empty() {
295            Ok(())
296        } else {
297            let errors = std::mem::take(&mut self.shutdown_errors);
298            anyhow::bail!("{context}: {}", errors.join("; "))
299        }
300    }
301
302    async fn finish_owned_task(
303        slot: &mut TaskSlot<Result<(), LighterWsError>>,
304        description: &str,
305        errors: &mut Vec<String>,
306    ) {
307        let Some(outcome) = finish_task(slot, DISCONNECT_TIMEOUT, DISCONNECT_TIMEOUT).await else {
308            return;
309        };
310
311        match outcome {
312            TaskJoinOutcome::Completed(Ok(())) | TaskJoinOutcome::Aborted => {}
313            TaskJoinOutcome::Completed(Err(e)) => {
314                errors.push(format!("{description} failed: {e}"));
315            }
316            TaskJoinOutcome::Failed(e) => {
317                errors.push(format!("{description} task failed: {e}"));
318            }
319            TaskJoinOutcome::Incomplete => {
320                errors.push(format!("{description} task did not stop after abort"));
321            }
322        }
323    }
324
325    async fn bootstrap_instruments(&self) -> anyhow::Result<Vec<InstrumentAny>> {
326        let instruments_with_status = self
327            .http_client
328            .request_instruments_with_status()
329            .await
330            .context("failed to fetch instruments during bootstrap")?;
331        let instruments: Vec<InstrumentAny> = instruments_with_status
332            .iter()
333            .map(|(instrument, _)| instrument.clone())
334            .collect();
335
336        let mut ws_cache: Vec<(i64, InstrumentAny)> = Vec::with_capacity(instruments.len());
337        self.instruments.rcu(|m| {
338            for instrument in &instruments {
339                m.insert(instrument.id(), instrument.clone());
340            }
341        });
342
343        for instrument in &instruments {
344            if let Some(market_index) = self.registry.market_index(&instrument.id()) {
345                ws_cache.push((market_index, instrument.clone()));
346            } else {
347                log::warn!(
348                    "No market_index registered for instrument {} during bootstrap",
349                    instrument.id(),
350                );
351            }
352        }
353
354        self.instrument_statuses.clear();
355        for (instrument, status) in &instruments_with_status {
356            cache_lighter_instrument_status(&self.instrument_statuses, instrument.id(), *status);
357        }
358
359        self.ws_client.cache_instruments(ws_cache);
360
361        log::debug!(
362            "Bootstrapped {} Lighter instruments ({} registry entries)",
363            self.instruments.len(),
364            self.registry.len(),
365        );
366        Ok(instruments)
367    }
368
369    async fn spawn_ws(&mut self) -> anyhow::Result<()> {
370        // Connect on a clone so the resulting `out_rx` (and inner handler
371        // task handle) live on the consumer; transfer the handle back to
372        // `self.ws_client` so disconnect() can await it.
373        let mut ws_guard = TaskRetentionGuard::new(
374            self.ws_client.clone(),
375            Arc::clone(&self.ws_handler_retained),
376        );
377        ws_guard
378            .client_mut()
379            .connect_with_cancellation(self.cancellation_token.clone())
380            .await
381            .context("failed to connect to Lighter WebSocket")?;
382
383        if let Err(e) = ws_guard.client_mut().wait_until_active().await {
384            let ws_client = ws_guard.disarm();
385            let mut rollback_errors = Vec::new();
386
387            if let Err(e) = ws_client
388                .disconnect_with_task_retention(Arc::clone(&self.ws_handler_retained))
389                .await
390            {
391                rollback_errors.push(e.to_string());
392            }
393
394            if let Err(e) = self.ws_handler_retained.finish().await {
395                rollback_errors.push(e.to_string());
396            }
397
398            let readiness_error =
399                anyhow::Error::new(e).context("Lighter WebSocket did not reach active state");
400
401            if rollback_errors.is_empty() {
402                return Err(readiness_error);
403            }
404            return Err(readiness_error.context(format!(
405                "Lighter WebSocket readiness rollback failed: {}",
406                rollback_errors.join("; ")
407            )));
408        }
409
410        let mut ws_client = ws_guard.disarm();
411        self.ws_client.set_task_slot(ws_client.take_task_slot());
412
413        let cancellation_token = self.cancellation_token.clone();
414        let data_sender = self.data_sender.clone();
415        let market_stats_subscriptions = Arc::clone(&self.market_stats_subscriptions);
416
417        let future = async move {
418            log::debug!("Lighter WebSocket consumption loop started");
419
420            loop {
421                tokio::select! {
422                    // Prefer cancellation so a buffered frame is not forwarded after cancel
423                    biased;
424                    () = cancellation_token.cancelled() => {
425                        log::debug!("Lighter WebSocket consumption loop cancelled");
426                        break;
427                    }
428                    msg_opt = ws_client.next_event() => {
429                        match msg_opt {
430                            Some(NautilusWsMessage::Trades(trades)) => {
431                                for trade in trades {
432                                    if let Err(e) = data_sender
433                                        .send(DataEvent::Data(Data::Trade(trade)))
434                                    {
435                                        log::error!("Failed to send trade tick: {e}");
436                                    }
437                                }
438                            }
439                            Some(NautilusWsMessage::Quote(quote)) => {
440                                if let Err(e) = data_sender
441                                    .send(DataEvent::Data(Data::Quote(quote)))
442                                {
443                                    log::error!("Failed to send quote tick: {e}");
444                                }
445                            }
446                            Some(NautilusWsMessage::Deltas(deltas)) => {
447                                let data = Data::BookDeltas(Box::new(deltas));
448                                if let Err(e) = data_sender.send(DataEvent::Data(data)) {
449                                    log::error!("Failed to send order book deltas: {e}");
450                                }
451                            }
452                            Some(NautilusWsMessage::Depth(depth)) => {
453                                if let Err(e) =
454                                    data_sender.send(DataEvent::Data(Data::BookDepth(depth)))
455                                {
456                                    log::error!("Failed to send order book depth: {e}");
457                                }
458                            }
459                            Some(NautilusWsMessage::Bar(bar)) => {
460                                if let Err(e) = data_sender.send(DataEvent::Data(Data::Bar(bar))) {
461                                    log::error!("Failed to send bar: {e}");
462                                }
463                            }
464                            Some(message @ (NautilusWsMessage::MarkPrice(_)
465                                | NautilusWsMessage::IndexPrice(_)
466                                | NautilusWsMessage::FundingRate(_))) =>
467                            {
468                                emit_market_stats_ws_message(
469                                    &data_sender,
470                                    &market_stats_subscriptions,
471                                    &message,
472                                );
473                            }
474                            Some(NautilusWsMessage::Raw(value)) => {
475                                log::debug!("Unhandled Lighter raw frame: {value}");
476                            }
477                            // The data client does not consume execution-side
478                            // reports; the execution client subscribes to its
479                            // own clone of the WebSocket and routes them.
480                            Some(
481                                NautilusWsMessage::ExecutionReports(_)
482                                | NautilusWsMessage::PositionSnapshot { .. }
483                                | NautilusWsMessage::PositionUpdate { .. }
484                                | NautilusWsMessage::AccountState(_)
485                                | NautilusWsMessage::AccountTx { .. }
486                                | NautilusWsMessage::SendTxAck { .. }
487                                | NautilusWsMessage::SendTxRejected { .. }
488                                | NautilusWsMessage::SendTxBatchResult { .. }
489                                | NautilusWsMessage::AccountStreamFirstFrame(_),
490                            ) => {}
491                            Some(NautilusWsMessage::Reconnected { .. }) => {
492                                log::debug!("Lighter WebSocket reconnected");
493                            }
494                            None => {
495                                log::debug!("Lighter WebSocket next_event returned None");
496                                tokio::select! {
497                                    () = cancellation_token.cancelled() => {
498                                        log::debug!(
499                                            "Lighter WebSocket consumption loop cancelled"
500                                        );
501                                        break;
502                                    }
503                                    () = tokio::time::sleep(tokio::time::Duration::from_secs(1)) => {}
504                                }
505                            }
506                        }
507                    }
508                }
509            }
510
511            log::debug!("Lighter WebSocket consumption loop finished");
512        };
513
514        self.tasks
515            .spawn(future)
516            .context("failed to register Lighter WebSocket consumption task")?;
517        log::debug!("Lighter WebSocket consumption task spawned");
518
519        Ok(())
520    }
521
522    fn spawn_instrument_refresh(&self) -> anyhow::Result<()> {
523        let minutes = self.config.update_instruments_interval_mins;
524        if minutes == 0 {
525            log::debug!("Lighter instrument refresh disabled (interval=0)");
526            return Ok(());
527        }
528
529        let interval = Duration::from_secs(minutes.saturating_mul(60));
530        let cancellation = self.cancellation_token.clone();
531        let http_client = self.http_client.clone();
532        let instruments_cache = Arc::clone(&self.instruments);
533        let statuses = Arc::clone(&self.instrument_statuses);
534        let status_subscriptions = Arc::clone(&self.instrument_status_subscriptions);
535        let registry = Arc::clone(&self.registry);
536        let ws_client = self.ws_client.clone();
537        let data_sender = self.data_sender.clone();
538        let client_id = self.client_id;
539        let clock = self.clock;
540
541        let future = async move {
542            loop {
543                let sleep = tokio::time::sleep(interval);
544                tokio::pin!(sleep);
545                tokio::select! {
546                    () = cancellation.cancelled() => {
547                        log::debug!("Lighter instrument refresh task cancelled");
548                        break;
549                    }
550                    () = &mut sleep => {
551                        let Some(result) = await_instrument_refresh(
552                            &cancellation,
553                            http_client.request_instruments_with_status(),
554                        ).await else {
555                            log::debug!("Lighter instrument refresh task cancelled");
556                            break;
557                        };
558
559                        match result {
560                            Ok(items) => {
561                                instruments_cache.rcu(|m| {
562                                    for (instrument, _) in &items {
563                                        m.insert(instrument.id(), instrument.clone());
564                                    }
565                                });
566
567                                let ws_cache: Vec<(i64, InstrumentAny)> = items
568                                    .iter()
569                                    .filter_map(|(instrument, _)| {
570                                        registry
571                                            .market_index(&instrument.id())
572                                            .map(|idx| (idx, instrument.clone()))
573                                    })
574                                    .collect();
575
576                                if !ws_cache.is_empty() {
577                                    ws_client.cache_instruments(ws_cache);
578                                }
579
580                                statuses.clear();
581                                let ts_init = clock.get_time_ns();
582
583                                for (instrument, status) in &items {
584                                    cache_lighter_instrument_status(
585                                        &statuses,
586                                        instrument.id(),
587                                        *status,
588                                    );
589                                    emit_lighter_instrument_status_if_subscribed(
590                                        &data_sender,
591                                        &status_subscriptions,
592                                        instrument.id(),
593                                        *status,
594                                        ts_init,
595                                        ts_init,
596                                    );
597
598                                    if let Err(e) = data_sender
599                                        .send(DataEvent::Data(instrument.clone().into()))
600                                    {
601                                        log::warn!(
602                                            "Failed to send refreshed Lighter instrument: {e}"
603                                        );
604                                    }
605                                }
606
607                                log::debug!(
608                                    "Lighter instruments refreshed: client_id={client_id}, count={}",
609                                    items.len(),
610                                );
611                            }
612                            Err(e) => {
613                                log::warn!(
614                                    "Failed to refresh Lighter instruments: client_id={client_id}, error={e:?}",
615                                );
616                            }
617                        }
618                    }
619                }
620            }
621        };
622
623        self.tasks
624            .spawn(future)
625            .context("failed to register Lighter instrument refresh task")?;
626        Ok(())
627    }
628
629    async fn teardown_partial_connect(&mut self) -> anyhow::Result<()> {
630        self.tasks.begin_shutdown();
631        self.ws_client.begin_shutdown();
632
633        if let Err(e) = self.shutdown_tasks().await {
634            self.shutdown_errors.push(e.to_string());
635        }
636        let ws_client = self.take_ws_client();
637        if let Err(e) = ws_client
638            .disconnect_with_task_retention(Arc::clone(&self.ws_handler_retained))
639            .await
640        {
641            self.shutdown_errors.push(e.to_string());
642        }
643
644        if let Err(e) = self.ws_handler_retained.finish().await {
645            self.shutdown_errors.push(e.to_string());
646        }
647        self.is_connected.store(false, Ordering::Release);
648
649        self.take_shutdown_result("Failed to roll back Lighter data startup")
650    }
651
652    fn clear_market_stats_subscriptions(&self) {
653        self.market_stats_subscriptions.clear();
654        self.market_stats_subscription_generations.clear();
655    }
656
657    fn clear_instrument_status_subscriptions(&self) {
658        self.instrument_status_subscriptions.clear();
659    }
660
661    fn emit_cached_instrument_status(&self, instrument_id: InstrumentId) -> bool {
662        let Some(status) = self
663            .instrument_statuses
664            .get(&instrument_id)
665            .map(|status| *status)
666        else {
667            return false;
668        };
669
670        let ts_init = self.clock.get_time_ns();
671        emit_lighter_instrument_status(&self.data_sender, instrument_id, status, ts_init, ts_init);
672        true
673    }
674
675    fn activate_market_stats_subscription(
676        &self,
677        instrument_id: InstrumentId,
678        channel: LighterWsChannel,
679        kind: MarketStatsKind,
680        label: &'static str,
681    ) {
682        let generation_entry = self
683            .market_stats_subscription_generations
684            .entry(instrument_id)
685            .or_insert_with(|| {
686                self.next_market_stats_subscription_generation
687                    .fetch_add(1, Ordering::Relaxed)
688            });
689        let generation = *generation_entry;
690
691        let subscribe_channel = match self.market_stats_subscriptions.entry(instrument_id) {
692            Entry::Occupied(mut entry) => {
693                let subscription = entry.get_mut();
694                let should_subscribe = subscription.flags.is_empty();
695                subscription.flags.insert(kind);
696                should_subscribe.then(|| subscription.channel.clone())
697            }
698            Entry::Vacant(entry) => {
699                entry.insert(MarketStatsSubscription::new(channel.clone(), kind));
700                Some(channel)
701            }
702        };
703        drop(generation_entry);
704
705        if let Some(channel) = subscribe_channel {
706            let ws = self.ws_client.clone();
707            let subscriptions = Arc::clone(&self.market_stats_subscriptions);
708            let generations = Arc::clone(&self.market_stats_subscription_generations);
709            self.spawn_task(async move {
710                if let Err(e) = subscribe_market_stats_channel(ws, channel).await {
711                    log::error!("Failed to subscribe to Lighter {label}: {e:?}");
712
713                    // The underlying channel never became active, so clear every request
714                    // piggybacked on this generation. A newer replacement is left intact.
715                    rollback_market_stats_subscription(
716                        &subscriptions,
717                        &generations,
718                        instrument_id,
719                        generation,
720                    );
721                }
722            });
723        }
724    }
725
726    fn deactivate_market_stats_subscription(
727        &self,
728        instrument_id: InstrumentId,
729        kind: MarketStatsKind,
730        label: &'static str,
731    ) {
732        // Hold the shard lock across removal so a concurrent activate cannot re-add an erased flag
733        let generation = self
734            .market_stats_subscription_generations
735            .entry(instrument_id);
736        let unsubscribe_channel = match self.market_stats_subscriptions.entry(instrument_id) {
737            Entry::Occupied(mut entry) => {
738                entry.get_mut().flags.remove(kind);
739                if entry.get().flags.is_empty() {
740                    if let Entry::Occupied(generation) = generation {
741                        generation.remove();
742                    }
743                    Some(entry.remove().channel)
744                } else {
745                    None
746                }
747            }
748            Entry::Vacant(_) => None,
749        };
750
751        if let Some(channel) = unsubscribe_channel {
752            let ws = self.ws_client.clone();
753            self.spawn_task(async move {
754                if let Err(e) = unsubscribe_market_stats_channel(ws, channel).await {
755                    log::error!("Failed to unsubscribe from Lighter {label}: {e:?}");
756                }
757            });
758        }
759    }
760
761    fn perp_market_stats_channel(
762        &self,
763        instrument_id: InstrumentId,
764        label: &str,
765    ) -> anyhow::Result<LighterWsChannel> {
766        let instrument = self
767            .instruments
768            .get_cloned(&instrument_id)
769            .ok_or_else(|| InstrumentLookupError::not_found(instrument_id))?;
770
771        anyhow::ensure!(
772            matches!(instrument, InstrumentAny::CryptoPerpetual(_)),
773            "Lighter {label} subscriptions require a perpetual instrument: {instrument_id}",
774        );
775
776        let market_index = self.registry.market_index(&instrument_id).ok_or_else(|| {
777            anyhow::anyhow!("No Lighter market_index registered for {instrument_id}")
778        })?;
779
780        Ok(LighterWsChannel::MarketStats(
781            LighterMarketSelection::Market(market_index),
782        ))
783    }
784
785    fn index_market_stats_channel(
786        &self,
787        instrument_id: InstrumentId,
788    ) -> anyhow::Result<LighterWsChannel> {
789        let instrument = self
790            .instruments
791            .get_cloned(&instrument_id)
792            .ok_or_else(|| InstrumentLookupError::not_found(instrument_id))?;
793        let market_index = self.registry.market_index(&instrument_id).ok_or_else(|| {
794            anyhow::anyhow!("No Lighter market_index registered for {instrument_id}")
795        })?;
796
797        match instrument {
798            InstrumentAny::CryptoPerpetual(_) => Ok(LighterWsChannel::MarketStats(
799                LighterMarketSelection::Market(market_index),
800            )),
801            InstrumentAny::CurrencyPair(_) => Ok(LighterWsChannel::SpotMarketStats(
802                LighterMarketSelection::Market(market_index),
803            )),
804            _ => anyhow::bail!(
805                "Lighter index price subscriptions require a perpetual or spot instrument: {instrument_id}",
806            ),
807        }
808    }
809}
810
811async fn await_instrument_refresh<T>(
812    cancellation: &CancellationToken,
813    request: impl std::future::Future<Output = T>,
814) -> Option<T> {
815    tokio::select! {
816        biased;
817        () = cancellation.cancelled() => None,
818        result = request => (!cancellation.is_cancelled()).then_some(result),
819    }
820}
821
822fn cache_lighter_instrument_status(
823    statuses: &DashMap<InstrumentId, LighterMarketStatus>,
824    instrument_id: InstrumentId,
825    status: LighterMarketStatus,
826) {
827    statuses.insert(instrument_id, status);
828}
829
830fn rollback_market_stats_subscription(
831    subscriptions: &DashMap<InstrumentId, MarketStatsSubscription>,
832    generations: &DashMap<InstrumentId, u64>,
833    instrument_id: InstrumentId,
834    failed_generation: u64,
835) {
836    let Entry::Occupied(generation) = generations.entry(instrument_id) else {
837        return;
838    };
839
840    if *generation.get() != failed_generation {
841        return;
842    }
843
844    subscriptions.remove(&instrument_id);
845    generation.remove();
846}
847
848fn emit_lighter_instrument_status_if_subscribed(
849    sender: &EventSender<DataEvent>,
850    subscriptions: &DashSet<InstrumentId>,
851    instrument_id: InstrumentId,
852    status: LighterMarketStatus,
853    ts_event: UnixNanos,
854    ts_init: UnixNanos,
855) {
856    if subscriptions.contains(&instrument_id) {
857        emit_lighter_instrument_status(sender, instrument_id, status, ts_event, ts_init);
858    }
859}
860
861fn emit_lighter_instrument_status(
862    sender: &EventSender<DataEvent>,
863    instrument_id: InstrumentId,
864    status: LighterMarketStatus,
865    ts_event: UnixNanos,
866    ts_init: UnixNanos,
867) {
868    let action = match lighter_market_status_action(status) {
869        Ok(action) => action,
870        Err(e) => {
871            log::warn!("Skipping Lighter instrument status for {instrument_id}: {e}");
872            return;
873        }
874    };
875
876    let is_trading = Some(matches!(action, MarketStatusAction::Trading));
877    let status = InstrumentStatus::new(
878        instrument_id,
879        action,
880        ts_event,
881        ts_init,
882        None,
883        None,
884        is_trading,
885        None,
886        None,
887    );
888
889    if let Err(e) = sender.send(DataEvent::Data(Data::InstrumentStatus(status))) {
890        log::error!("Failed to send Lighter instrument status: {e}");
891    }
892}
893
894fn lighter_market_status_action(status: LighterMarketStatus) -> anyhow::Result<MarketStatusAction> {
895    match status {
896        LighterMarketStatus::Active => Ok(MarketStatusAction::Trading),
897        LighterMarketStatus::Inactive => Ok(MarketStatusAction::NotAvailableForTrading),
898        LighterMarketStatus::InSettlement
899        | LighterMarketStatus::WaitingForSettlement
900        | LighterMarketStatus::Settled
901        | LighterMarketStatus::Unknown => Err(anyhow::anyhow!(
902            "Lighter market status `{status}` has no Nautilus market status action",
903        )),
904    }
905}
906
907#[async_trait::async_trait(?Send)]
908impl DataClient for LighterDataClient {
909    fn client_id(&self) -> ClientId {
910        self.client_id
911    }
912
913    fn venue(&self) -> Option<Venue> {
914        Some(self.venue())
915    }
916
917    fn start(&mut self) -> anyhow::Result<()> {
918        log::info!(
919            "Starting Lighter data client: client_id={}, environment={:?}, has_credentials={}",
920            self.client_id,
921            self.config.environment,
922            self.has_credentials(),
923        );
924        Ok(())
925    }
926
927    fn stop(&mut self) -> anyhow::Result<()> {
928        log::info!("Stopping Lighter data client {}", self.client_id);
929        self.abort_tasks();
930        self.spawn_ws_disconnect();
931        self.is_connected.store(false, Ordering::Release);
932        self.clear_instrument_status_subscriptions();
933        self.clear_market_stats_subscriptions();
934        Ok(())
935    }
936
937    fn reset(&mut self) -> anyhow::Result<()> {
938        log::debug!("Resetting Lighter data client {}", self.client_id);
939        self.abort_tasks();
940        self.spawn_ws_disconnect();
941        self.is_connected.store(false, Ordering::Release);
942        self.clear_instrument_status_subscriptions();
943        self.clear_market_stats_subscriptions();
944        Ok(())
945    }
946
947    fn dispose(&mut self) -> anyhow::Result<()> {
948        log::debug!("Disposing Lighter data client {}", self.client_id);
949        self.stop()
950    }
951
952    fn is_connected(&self) -> bool {
953        self.is_connected.load(Ordering::Acquire)
954    }
955
956    fn is_disconnected(&self) -> bool {
957        !self.is_connected()
958    }
959
960    async fn connect(&mut self) -> anyhow::Result<()> {
961        if self.is_connected()
962            && self.tasks.is_open()
963            && self.ws_disconnect_handle.is_none()
964            && self.ws_handler_retained.is_empty()
965        {
966            return Ok(());
967        }
968
969        if !self.tasks.is_open()
970            || !self.tasks.is_empty()
971            || self.ws_disconnect_handle.is_some()
972            || !self.ws_handler_retained.is_empty()
973        {
974            self.teardown_partial_connect().await?;
975        }
976
977        if !self.tasks.is_open() {
978            self.tasks.start_generation().map_err(|e| {
979                anyhow::anyhow!("Failed to start Lighter data task generation: {e}")
980            })?;
981            self.cancellation_token = self.tasks.cancellation_token();
982        }
983
984        let ws_client = self.ws_client.clone();
985        let setup_guard = TaskGroupGuard::new(&[&self.tasks], move || {
986            ws_client.begin_shutdown();
987        });
988
989        let instruments = self
990            .bootstrap_instruments()
991            .await
992            .context("failed to bootstrap Lighter instruments")?;
993
994        for instrument in instruments {
995            if let Err(e) = self.data_sender.send(DataEvent::Data(instrument.into())) {
996                log::warn!("Failed to send instrument: {e}");
997            }
998        }
999
1000        let session_result = async {
1001            self.spawn_ws()
1002                .await
1003                .context("failed to spawn Lighter WebSocket consumer")?;
1004            self.spawn_instrument_refresh()?;
1005            Ok::<(), anyhow::Error>(())
1006        }
1007        .await;
1008
1009        if let Err(e) = session_result {
1010            if let Err(teardown_error) = self.teardown_partial_connect().await {
1011                return Err(e.context(format!(
1012                    "Lighter data startup teardown failed: {teardown_error}"
1013                )));
1014            }
1015            return Err(e);
1016        }
1017
1018        setup_guard.disarm();
1019        self.is_connected.store(true, Ordering::Relaxed);
1020        log::info!("Connected: client_id={}", self.client_id);
1021
1022        Ok(())
1023    }
1024
1025    async fn disconnect(&mut self) -> anyhow::Result<()> {
1026        if !self.is_connected()
1027            && self.tasks.is_empty()
1028            && self.tasks.is_open()
1029            && self.ws_disconnect_handle.is_none()
1030            && self.ws_handler_retained.is_empty()
1031            && self.shutdown_errors.is_empty()
1032        {
1033            return Ok(());
1034        }
1035
1036        self.tasks.begin_shutdown();
1037        self.ws_client.begin_shutdown();
1038        self.clear_instrument_status_subscriptions();
1039        self.clear_market_stats_subscriptions();
1040
1041        if let Err(e) = self.shutdown_tasks().await {
1042            self.shutdown_errors.push(e.to_string());
1043        }
1044
1045        let ws_client = self.take_ws_client();
1046        if let Err(e) = ws_client
1047            .disconnect_with_task_retention(Arc::clone(&self.ws_handler_retained))
1048            .await
1049        {
1050            self.shutdown_errors.push(e.to_string());
1051        }
1052
1053        if let Err(e) = self.ws_handler_retained.finish().await {
1054            self.shutdown_errors.push(e.to_string());
1055        }
1056
1057        self.instruments.store(AHashMap::new());
1058        self.instrument_statuses.clear();
1059        self.registry.clear();
1060
1061        self.is_connected.store(false, Ordering::Relaxed);
1062        log::info!("Disconnected: client_id={}", self.client_id);
1063
1064        self.take_shutdown_result("Failed to disconnect Lighter data client")
1065    }
1066
1067    fn subscribe_instrument(&mut self, cmd: SubscribeInstrument) -> anyhow::Result<()> {
1068        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1069            let instruments = self.instruments.load();
1070            if let Some(instrument) = instruments.get(&instrument_id) {
1071                if let Err(e) = self
1072                    .data_sender
1073                    .send(DataEvent::Data(instrument.clone().into()))
1074                {
1075                    log::error!("Failed to send instrument {instrument_id}: {e}");
1076                }
1077            } else {
1078                log::warn!("Instrument {instrument_id} not found in cache");
1079            }
1080
1081            Ok(())
1082        })
1083    }
1084
1085    fn unsubscribe_instrument(&mut self, cmd: &UnsubscribeInstrument) -> anyhow::Result<()> {
1086        execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1087            log::debug!("Unsubscribing from instrument: {instrument_id} (cache replay only)",);
1088            Ok(())
1089        })
1090    }
1091
1092    fn subscribe_instrument_status(
1093        &mut self,
1094        subscription: SubscribeInstrumentStatus,
1095    ) -> anyhow::Result<()> {
1096        execute_instrument_subscriptions(&subscription.instrument_ids, |instrument_id| {
1097            self.instrument_status_subscriptions.insert(instrument_id);
1098            if self.emit_cached_instrument_status(instrument_id) {
1099                return Ok(());
1100            }
1101
1102            let http = self.http_client.clone();
1103            let ws = self.ws_client.clone();
1104            let registry = Arc::clone(&self.registry);
1105            let sender = self.data_sender.clone();
1106            let instruments_cache = Arc::clone(&self.instruments);
1107            let statuses = Arc::clone(&self.instrument_statuses);
1108            let subscriptions = Arc::clone(&self.instrument_status_subscriptions);
1109            let clock = self.clock;
1110
1111            self.spawn_task(async move {
1112                match http.request_instrument_with_status(instrument_id).await {
1113                    Ok((instrument, status)) => {
1114                        instruments_cache.rcu(|map| {
1115                            map.insert(instrument.id(), instrument.clone());
1116                        });
1117
1118                        if let Some(market_index) = registry.market_index(&instrument.id()) {
1119                            ws.cache_instrument(market_index, instrument.clone());
1120                        }
1121
1122                        cache_lighter_instrument_status(&statuses, instrument.id(), status);
1123                        let ts_init = clock.get_time_ns();
1124                        emit_lighter_instrument_status_if_subscribed(
1125                            &sender,
1126                            &subscriptions,
1127                            instrument.id(),
1128                            status,
1129                            ts_init,
1130                            ts_init,
1131                        );
1132                    }
1133                    Err(e) => {
1134                        log::error!(
1135                            "Failed to fetch Lighter instrument status for {instrument_id}: {e:?}"
1136                        );
1137                    }
1138                }
1139            });
1140
1141            Ok(())
1142        })
1143    }
1144
1145    fn subscribe_book_deltas(&mut self, subscription: SubscribeBookDeltas) -> anyhow::Result<()> {
1146        execute_instrument_subscriptions(&subscription.instrument_ids, |instrument_id| {
1147            let subscription = subscription.with_instrument_ids(instrument_id);
1148            validate_book_deltas_subscription(subscription.book_type)?;
1149
1150            let ws = self.ws_client.clone();
1151            self.spawn_task(async move {
1152                if let Err(e) = ws.subscribe_book(instrument_id).await {
1153                    log::error!("Failed to subscribe to Lighter book deltas: {e:?}");
1154                }
1155            });
1156
1157            Ok(())
1158        })
1159    }
1160
1161    fn subscribe_book_depth(&mut self, subscription: SubscribeBookDepth) -> anyhow::Result<()> {
1162        execute_instrument_subscriptions(&subscription.instrument_ids, |instrument_id| {
1163            let subscription = subscription.with_instrument_ids(instrument_id);
1164            log::debug!("Subscribing to book depth: {instrument_id}");
1165
1166            validate_book_depth_subscription(subscription.book_type)?;
1167
1168            let ws = self.ws_client.clone();
1169            self.spawn_task(async move {
1170                if let Err(e) = ws.subscribe_book_depth(instrument_id).await {
1171                    log::error!("Failed to subscribe to Lighter book depth: {e:?}");
1172                }
1173            });
1174
1175            Ok(())
1176        })
1177    }
1178
1179    fn subscribe_quotes(&mut self, subscription: SubscribeQuotes) -> anyhow::Result<()> {
1180        execute_instrument_subscriptions(&subscription.instrument_ids, |instrument_id| {
1181            let ws = self.ws_client.clone();
1182            self.spawn_task(async move {
1183                if let Err(e) = ws.subscribe_quotes(instrument_id).await {
1184                    log::error!("Failed to subscribe to Lighter quotes: {e:?}");
1185                }
1186            });
1187
1188            Ok(())
1189        })
1190    }
1191
1192    fn subscribe_trades(&mut self, subscription: SubscribeTrades) -> anyhow::Result<()> {
1193        execute_instrument_subscriptions(&subscription.instrument_ids, |instrument_id| {
1194            let ws = self.ws_client.clone();
1195            self.spawn_task(async move {
1196                if let Err(e) = ws.subscribe_trades(instrument_id).await {
1197                    log::error!("Failed to subscribe to Lighter trades: {e:?}");
1198                }
1199            });
1200
1201            Ok(())
1202        })
1203    }
1204
1205    fn subscribe_mark_prices(&mut self, subscription: SubscribeMarkPrices) -> anyhow::Result<()> {
1206        execute_instrument_subscriptions(&subscription.instrument_ids, |instrument_id| {
1207            let channel = self.perp_market_stats_channel(instrument_id, "mark price")?;
1208            self.activate_market_stats_subscription(
1209                instrument_id,
1210                channel,
1211                MarketStatsKind::MarkPrice,
1212                "mark price",
1213            );
1214
1215            Ok(())
1216        })
1217    }
1218
1219    fn subscribe_index_prices(&mut self, subscription: SubscribeIndexPrices) -> anyhow::Result<()> {
1220        execute_instrument_subscriptions(&subscription.instrument_ids, |instrument_id| {
1221            let channel = self.index_market_stats_channel(instrument_id)?;
1222            self.activate_market_stats_subscription(
1223                instrument_id,
1224                channel,
1225                MarketStatsKind::IndexPrice,
1226                "index price",
1227            );
1228
1229            Ok(())
1230        })
1231    }
1232
1233    fn subscribe_funding_rates(
1234        &mut self,
1235        subscription: SubscribeFundingRates,
1236    ) -> anyhow::Result<()> {
1237        execute_instrument_subscriptions(&subscription.instrument_ids, |instrument_id| {
1238            let channel = self.perp_market_stats_channel(instrument_id, "funding rate")?;
1239            self.activate_market_stats_subscription(
1240                instrument_id,
1241                channel,
1242                MarketStatsKind::FundingRate,
1243                "funding rate",
1244            );
1245
1246            Ok(())
1247        })
1248    }
1249
1250    fn subscribe_bars(&mut self, subscription: SubscribeBars) -> anyhow::Result<()> {
1251        execute_bar_subscriptions(&subscription.bar_types, |bar_type| {
1252            let resolution = LighterCandleResolution::try_from(&bar_type)?;
1253            anyhow::ensure!(
1254                resolution.is_ws_streamable(),
1255                "Lighter does not offer {bar_type} on the candle WebSocket stream",
1256            );
1257
1258            let instrument_id = bar_type.instrument_id();
1259            if !self.instruments.contains_key(&instrument_id) {
1260                return Err(InstrumentLookupError::not_found(instrument_id).into());
1261            }
1262
1263            let ws = self.ws_client.clone();
1264            self.spawn_task(async move {
1265                if let Err(e) = ws.subscribe_candles(instrument_id, resolution).await {
1266                    log::error!("Failed to subscribe to Lighter candles for {bar_type}: {e:?}");
1267                }
1268            });
1269
1270            Ok(())
1271        })
1272    }
1273
1274    fn unsubscribe_book_deltas(
1275        &mut self,
1276        unsubscription: &UnsubscribeBookDeltas,
1277    ) -> anyhow::Result<()> {
1278        execute_instrument_subscriptions(&unsubscription.instrument_ids, |instrument_id| {
1279            log::debug!("Unsubscribing from book deltas: {instrument_id}");
1280
1281            let ws = self.ws_client.clone();
1282            self.spawn_task(async move {
1283                if let Err(e) = ws.unsubscribe_book(instrument_id).await {
1284                    log::error!("Failed to unsubscribe from Lighter book deltas: {e:?}");
1285                }
1286            });
1287
1288            Ok(())
1289        })
1290    }
1291
1292    fn unsubscribe_book_depth(
1293        &mut self,
1294        unsubscription: &UnsubscribeBookDepth,
1295    ) -> anyhow::Result<()> {
1296        execute_instrument_subscriptions(&unsubscription.instrument_ids, |instrument_id| {
1297            log::debug!("Unsubscribing from book depth: {instrument_id}");
1298
1299            let ws = self.ws_client.clone();
1300            self.spawn_task(async move {
1301                if let Err(e) = ws.unsubscribe_book_depth(instrument_id).await {
1302                    log::error!("Failed to unsubscribe from Lighter book depth: {e:?}");
1303                }
1304            });
1305
1306            Ok(())
1307        })
1308    }
1309
1310    fn unsubscribe_quotes(&mut self, unsubscription: &UnsubscribeQuotes) -> anyhow::Result<()> {
1311        execute_instrument_subscriptions(&unsubscription.instrument_ids, |instrument_id| {
1312            log::debug!("Unsubscribing from quotes: {instrument_id}");
1313
1314            let ws = self.ws_client.clone();
1315            self.spawn_task(async move {
1316                if let Err(e) = ws.unsubscribe_quotes(instrument_id).await {
1317                    log::error!("Failed to unsubscribe from Lighter quotes: {e:?}");
1318                }
1319            });
1320
1321            Ok(())
1322        })
1323    }
1324
1325    fn unsubscribe_trades(&mut self, unsubscription: &UnsubscribeTrades) -> anyhow::Result<()> {
1326        execute_instrument_subscriptions(&unsubscription.instrument_ids, |instrument_id| {
1327            log::debug!("Unsubscribing from trades: {instrument_id}");
1328
1329            let ws = self.ws_client.clone();
1330            self.spawn_task(async move {
1331                if let Err(e) = ws.unsubscribe_trades(instrument_id).await {
1332                    log::error!("Failed to unsubscribe from Lighter trades: {e:?}");
1333                }
1334            });
1335
1336            Ok(())
1337        })
1338    }
1339
1340    fn unsubscribe_instrument_status(
1341        &mut self,
1342        unsubscription: &UnsubscribeInstrumentStatus,
1343    ) -> anyhow::Result<()> {
1344        execute_instrument_subscriptions(&unsubscription.instrument_ids, |instrument_id| {
1345            self.instrument_status_subscriptions.remove(&instrument_id);
1346
1347            Ok(())
1348        })
1349    }
1350
1351    fn unsubscribe_mark_prices(
1352        &mut self,
1353        unsubscription: &UnsubscribeMarkPrices,
1354    ) -> anyhow::Result<()> {
1355        execute_instrument_subscriptions(&unsubscription.instrument_ids, |instrument_id| {
1356            self.deactivate_market_stats_subscription(
1357                instrument_id,
1358                MarketStatsKind::MarkPrice,
1359                "mark price",
1360            );
1361
1362            Ok(())
1363        })
1364    }
1365
1366    fn unsubscribe_index_prices(
1367        &mut self,
1368        unsubscription: &UnsubscribeIndexPrices,
1369    ) -> anyhow::Result<()> {
1370        execute_instrument_subscriptions(&unsubscription.instrument_ids, |instrument_id| {
1371            self.deactivate_market_stats_subscription(
1372                instrument_id,
1373                MarketStatsKind::IndexPrice,
1374                "index price",
1375            );
1376
1377            Ok(())
1378        })
1379    }
1380
1381    fn unsubscribe_funding_rates(
1382        &mut self,
1383        unsubscription: &UnsubscribeFundingRates,
1384    ) -> anyhow::Result<()> {
1385        execute_instrument_subscriptions(&unsubscription.instrument_ids, |instrument_id| {
1386            self.deactivate_market_stats_subscription(
1387                instrument_id,
1388                MarketStatsKind::FundingRate,
1389                "funding rate",
1390            );
1391
1392            Ok(())
1393        })
1394    }
1395
1396    fn unsubscribe_bars(&mut self, unsubscription: &UnsubscribeBars) -> anyhow::Result<()> {
1397        execute_bar_subscriptions(&unsubscription.bar_types, |bar_type| {
1398            let resolution = match LighterCandleResolution::try_from(&bar_type) {
1399                Ok(resolution) => resolution,
1400                Err(e) => {
1401                    log::warn!("Skipping Lighter candle unsubscribe for {bar_type}: {e}");
1402                    return Ok(());
1403                }
1404            };
1405
1406            let instrument_id = bar_type.instrument_id();
1407            let ws = self.ws_client.clone();
1408            self.spawn_task(async move {
1409                if let Err(e) = ws.unsubscribe_candles(instrument_id, resolution).await {
1410                    log::error!("Failed to unsubscribe from Lighter candles for {bar_type}: {e:?}");
1411                }
1412            });
1413
1414            Ok(())
1415        })
1416    }
1417
1418    fn request_instruments(&self, request: RequestInstruments) -> anyhow::Result<()> {
1419        log::debug!("Requesting Lighter instruments");
1420
1421        let http = self.http_client.clone();
1422        let ws = self.ws_client.clone();
1423        let registry = Arc::clone(&self.registry);
1424        let sender = self.data_sender.clone();
1425        let instruments_cache = Arc::clone(&self.instruments);
1426        let status_cache = Arc::clone(&self.instrument_statuses);
1427        let status_subscriptions = Arc::clone(&self.instrument_status_subscriptions);
1428        let request_id = request.request_id;
1429        let client_id = request.client_id.unwrap_or(self.client_id);
1430        let venue = self.venue();
1431        let start_nanos = datetime_to_unix_nanos(request.start);
1432        let end_nanos = datetime_to_unix_nanos(request.end);
1433        let params = request.params;
1434        let clock = self.clock;
1435
1436        self.spawn_task(async move {
1437            match http.request_instruments_with_status().await {
1438                Ok(instruments_with_status) => {
1439                    let instruments: Vec<InstrumentAny> = instruments_with_status
1440                        .iter()
1441                        .map(|(instrument, _)| instrument.clone())
1442                        .collect();
1443
1444                    instruments_cache.rcu(|map| {
1445                        for instrument in &instruments {
1446                            map.insert(instrument.id(), instrument.clone());
1447                        }
1448                    });
1449
1450                    let ws_cache: Vec<(i64, InstrumentAny)> = instruments
1451                        .iter()
1452                        .filter_map(|i| registry.market_index(&i.id()).map(|idx| (idx, i.clone())))
1453                        .collect();
1454
1455                    if !ws_cache.is_empty() {
1456                        ws.cache_instruments(ws_cache);
1457                    }
1458
1459                    status_cache.clear();
1460                    let ts_init = clock.get_time_ns();
1461
1462                    for (instrument, status) in &instruments_with_status {
1463                        cache_lighter_instrument_status(&status_cache, instrument.id(), *status);
1464                        emit_lighter_instrument_status_if_subscribed(
1465                            &sender,
1466                            &status_subscriptions,
1467                            instrument.id(),
1468                            *status,
1469                            ts_init,
1470                            ts_init,
1471                        );
1472                    }
1473
1474                    let response = DataResponse::Instruments(InstrumentsResponse::new(
1475                        request_id,
1476                        client_id,
1477                        venue,
1478                        instruments,
1479                        start_nanos,
1480                        end_nanos,
1481                        clock.get_time_ns(),
1482                        params,
1483                    ));
1484
1485                    if let Err(e) = sender.send(DataEvent::Response(response)) {
1486                        log::error!("Failed to send instruments response: {e}");
1487                    }
1488                }
1489                Err(e) => {
1490                    log::error!("Failed to fetch Lighter instruments: {e:?}");
1491                }
1492            }
1493        });
1494
1495        Ok(())
1496    }
1497
1498    fn request_instrument(&self, request: RequestInstrument) -> anyhow::Result<()> {
1499        let instrument_id = request.single_instrument_id()?;
1500
1501        log::debug!("Requesting Lighter instrument: {instrument_id}");
1502
1503        let http = self.http_client.clone();
1504        let ws = self.ws_client.clone();
1505        let registry = Arc::clone(&self.registry);
1506        let sender = self.data_sender.clone();
1507        let instruments_cache = Arc::clone(&self.instruments);
1508        let status_cache = Arc::clone(&self.instrument_statuses);
1509        let status_subscriptions = Arc::clone(&self.instrument_status_subscriptions);
1510        let request_id = request.request_id;
1511        let client_id = request.client_id.unwrap_or(self.client_id);
1512        let start_nanos = datetime_to_unix_nanos(request.start);
1513        let end_nanos = datetime_to_unix_nanos(request.end);
1514        let params = request.params;
1515        let clock = self.clock;
1516
1517        self.spawn_task(async move {
1518            match http.request_instrument_with_status(instrument_id).await {
1519                Ok((instrument, status)) => {
1520                    instruments_cache.rcu(|map| {
1521                        map.insert(instrument.id(), instrument.clone());
1522                    });
1523
1524                    if let Some(market_index) = registry.market_index(&instrument.id()) {
1525                        ws.cache_instrument(market_index, instrument.clone());
1526                    }
1527
1528                    cache_lighter_instrument_status(&status_cache, instrument.id(), status);
1529                    let ts_init = clock.get_time_ns();
1530                    emit_lighter_instrument_status_if_subscribed(
1531                        &sender,
1532                        &status_subscriptions,
1533                        instrument.id(),
1534                        status,
1535                        ts_init,
1536                        ts_init,
1537                    );
1538
1539                    let response = DataResponse::Instrument(Box::new(InstrumentResponse::new(
1540                        request_id,
1541                        client_id,
1542                        instrument.id(),
1543                        instrument,
1544                        start_nanos,
1545                        end_nanos,
1546                        clock.get_time_ns(),
1547                        params,
1548                    )));
1549
1550                    if let Err(e) = sender.send(DataEvent::Response(response)) {
1551                        log::error!("Failed to send instrument response: {e}");
1552                    }
1553                }
1554                Err(e) => {
1555                    log::error!("Failed to fetch Lighter instrument {instrument_id}: {e:?}");
1556                }
1557            }
1558        });
1559
1560        Ok(())
1561    }
1562
1563    fn request_bars(&self, request: RequestBars) -> anyhow::Result<()> {
1564        let bar_type = request.single_bar_type()?;
1565
1566        log::debug!("Requesting Lighter bars for {bar_type}");
1567
1568        LighterCandleResolution::try_from(&bar_type)?;
1569
1570        let instrument_id = bar_type.instrument_id();
1571        let instrument = self
1572            .instruments
1573            .get_cloned(&instrument_id)
1574            .ok_or_else(|| InstrumentLookupError::not_found(instrument_id))?;
1575
1576        let http = self.http_client.clone();
1577        let sender = self.data_sender.clone();
1578        let start = request.start;
1579        let end = request.end;
1580        let limit = request.limit.map(|n| n.get() as u32);
1581        let request_id = request.request_id;
1582        let client_id = request.client_id.unwrap_or(self.client_id);
1583        let params = request.params;
1584        let clock = self.clock;
1585        let start_nanos = datetime_to_unix_nanos(start);
1586        let end_nanos = datetime_to_unix_nanos(end);
1587
1588        self.spawn_task(async move {
1589            match http
1590                .request_bars(&instrument, bar_type, start, end, limit)
1591                .await
1592            {
1593                Ok(bars) => {
1594                    let response = DataResponse::Bars(BarsResponse::new(
1595                        request_id,
1596                        client_id,
1597                        bar_type,
1598                        bars,
1599                        start_nanos,
1600                        end_nanos,
1601                        clock.get_time_ns(),
1602                        params,
1603                    ));
1604
1605                    if let Err(e) = sender.send(DataEvent::Response(response)) {
1606                        log::error!("Failed to send bars response: {e}");
1607                    }
1608                }
1609                Err(e) => {
1610                    log::error!("Lighter bars request failed for {instrument_id}: {e:?}");
1611                }
1612            }
1613        });
1614
1615        Ok(())
1616    }
1617
1618    fn request_quotes(&self, request: RequestQuotes) -> anyhow::Result<()> {
1619        let instrument_id = request.single_instrument_id()?;
1620
1621        anyhow::bail!(
1622            "Lighter does not support historical quote requests for {instrument_id}; \
1623             subscribe to quotes via WebSocket for live BBO ticks"
1624        )
1625    }
1626
1627    fn request_trades(&self, request: RequestTrades) -> anyhow::Result<()> {
1628        let instrument_id = request.single_instrument_id()?;
1629
1630        log::debug!("Requesting Lighter trades for {instrument_id}");
1631
1632        let instrument = self
1633            .instruments
1634            .get_cloned(&instrument_id)
1635            .ok_or_else(|| InstrumentLookupError::not_found(instrument_id))?;
1636
1637        let http = self.http_client.clone();
1638        let sender = self.data_sender.clone();
1639        let request_id = request.request_id;
1640        let client_id = request.client_id.unwrap_or(self.client_id);
1641        let limit = clamp_recent_trades_limit(request.limit);
1642        let start_nanos = datetime_to_unix_nanos(request.start);
1643        let end_nanos = datetime_to_unix_nanos(request.end);
1644        let params = request.params;
1645        let clock = self.clock;
1646
1647        self.spawn_task(async move {
1648            match http.request_recent_trades(&instrument, limit).await {
1649                Ok(mut trades) => {
1650                    retain_trade_ticks_in_range(&mut trades, start_nanos, end_nanos);
1651
1652                    let response = DataResponse::Trades(TradesResponse::new(
1653                        request_id,
1654                        client_id,
1655                        instrument_id,
1656                        trades,
1657                        start_nanos,
1658                        end_nanos,
1659                        clock.get_time_ns(),
1660                        params,
1661                    ));
1662
1663                    if let Err(e) = sender.send(DataEvent::Response(response)) {
1664                        log::error!("Failed to send trades response: {e}");
1665                    }
1666                }
1667                Err(e) => {
1668                    log::error!("Lighter trades request failed for {instrument_id}: {e}");
1669                }
1670            }
1671        });
1672
1673        Ok(())
1674    }
1675
1676    fn request_funding_rates(&self, request: RequestFundingRates) -> anyhow::Result<()> {
1677        let instrument_id = request.single_instrument_id()?;
1678
1679        log::debug!("Requesting Lighter funding rates for {instrument_id}");
1680
1681        let instrument = self
1682            .instruments
1683            .get_cloned(&instrument_id)
1684            .ok_or_else(|| InstrumentLookupError::not_found(instrument_id))?;
1685
1686        anyhow::ensure!(
1687            matches!(instrument, InstrumentAny::CryptoPerpetual(_)),
1688            "Lighter funding-rate requests require a perpetual instrument: {instrument_id}",
1689        );
1690
1691        let http = self.http_client.clone();
1692        let sender = self.data_sender.clone();
1693        let request_id = request.request_id;
1694        let client_id = request.client_id.unwrap_or(self.client_id);
1695        let start = request.start;
1696        let end = request.end;
1697        let limit = request.limit.map(|n| n.get());
1698        let start_nanos = datetime_to_unix_nanos(start);
1699        let end_nanos = datetime_to_unix_nanos(end);
1700        let params = request.params;
1701        let clock = self.clock;
1702
1703        self.spawn_task(async move {
1704            match http
1705                .request_funding_rates(&instrument, start, end, limit)
1706                .await
1707            {
1708                Ok(funding_rates) => {
1709                    let response = DataResponse::FundingRates(FundingRatesResponse::new(
1710                        request_id,
1711                        client_id,
1712                        instrument_id,
1713                        funding_rates,
1714                        start_nanos,
1715                        end_nanos,
1716                        clock.get_time_ns(),
1717                        params,
1718                    ));
1719
1720                    if let Err(e) = sender.send(DataEvent::Response(response)) {
1721                        log::error!("Failed to send funding rates response: {e}");
1722                    }
1723                }
1724                Err(e) => {
1725                    log::error!("Lighter funding rates request failed for {instrument_id}: {e:?}");
1726                }
1727            }
1728        });
1729
1730        Ok(())
1731    }
1732
1733    fn request_book_snapshot(&self, request: RequestBookSnapshot) -> anyhow::Result<()> {
1734        let instrument_id = request.single_instrument_id()?;
1735
1736        log::debug!("Requesting Lighter book snapshot for {instrument_id}");
1737
1738        let instrument = self
1739            .instruments
1740            .get_cloned(&instrument_id)
1741            .ok_or_else(|| InstrumentLookupError::not_found(instrument_id))?;
1742
1743        let market_index = self.registry.market_index(&instrument_id).ok_or_else(|| {
1744            anyhow::anyhow!("No Lighter market_index registered for {instrument_id}")
1745        })?;
1746
1747        let http = self.http_client.clone();
1748        let sender = self.data_sender.clone();
1749        let request_id = request.request_id;
1750        let client_id = request.client_id.unwrap_or(self.client_id);
1751        let limit = clamp_book_snapshot_limit(request.depth);
1752        let params = request.params;
1753        let clock = self.clock;
1754        let price_precision = instrument.price_precision();
1755        let size_precision = instrument.size_precision();
1756
1757        let query = LighterOrderBookOrdersQuery {
1758            market_id: market_index,
1759            limit,
1760        };
1761
1762        self.spawn_task(async move {
1763            match http.inner.get_order_book_orders(&query).await {
1764                Ok(snapshot) => {
1765                    let ts_init = clock.get_time_ns();
1766                    let book = parse_l2_order_book_snapshot(
1767                        &snapshot,
1768                        instrument_id,
1769                        price_precision,
1770                        size_precision,
1771                    );
1772
1773                    let response = DataResponse::Book(BookResponse::new(
1774                        request_id,
1775                        client_id,
1776                        instrument_id,
1777                        book,
1778                        None,
1779                        None,
1780                        ts_init,
1781                        params,
1782                    ));
1783
1784                    if let Err(e) = sender.send(DataEvent::Response(response)) {
1785                        log::error!("Failed to send book snapshot response: {e}");
1786                    }
1787                }
1788                Err(e) => {
1789                    log::error!("Lighter book snapshot request failed for {instrument_id}: {e:?}");
1790                }
1791            }
1792        });
1793
1794        Ok(())
1795    }
1796
1797    fn request_book_depth(&self, request: RequestBookDepth) -> anyhow::Result<()> {
1798        let instrument_id = request.single_instrument_id()?;
1799
1800        anyhow::bail!(
1801            "Lighter does not support historical order book depth requests for {instrument_id}; \
1802             use request_book_snapshot for an L2 snapshot or subscribe_book_depth for live depth"
1803        )
1804    }
1805}
1806
1807fn retain_trade_ticks_in_range(
1808    trades: &mut Vec<TradeTick>,
1809    start_nanos: Option<UnixNanos>,
1810    end_nanos: Option<UnixNanos>,
1811) {
1812    trades.retain(|trade| trade_tick_in_range(trade.ts_event, start_nanos, end_nanos));
1813    trades.sort_by_key(|trade| trade.ts_event);
1814}
1815
1816fn trade_tick_in_range(
1817    ts_event: UnixNanos,
1818    start_nanos: Option<UnixNanos>,
1819    end_nanos: Option<UnixNanos>,
1820) -> bool {
1821    start_nanos.is_none_or(|start| ts_event >= start) && end_nanos.is_none_or(|end| ts_event <= end)
1822}
1823
1824/// Returns an error if `book_type` is not [`BookType::L2_MBP`].
1825///
1826/// Lighter publishes only level-aggregated book updates, so any other book
1827/// type cannot be served by the WebSocket feed.
1828fn validate_book_deltas_subscription(book_type: BookType) -> anyhow::Result<()> {
1829    validate_l2_mbp_book_type(book_type, "deltas")
1830}
1831
1832fn validate_book_depth_subscription(book_type: BookType) -> anyhow::Result<()> {
1833    validate_l2_mbp_book_type(book_type, "depth")
1834}
1835
1836fn validate_l2_mbp_book_type(book_type: BookType, label: &str) -> anyhow::Result<()> {
1837    anyhow::ensure!(
1838        book_type == BookType::L2_MBP,
1839        "Lighter only supports L2_MBP order book {label}",
1840    );
1841    Ok(())
1842}
1843
1844#[cfg(test)]
1845mod tests {
1846    use std::{num::NonZeroUsize, time::Duration};
1847
1848    use axum::{
1849        Router,
1850        extract::Query,
1851        http::StatusCode,
1852        response::{IntoResponse, Response},
1853        routing::get,
1854    };
1855    use jiff::Timestamp;
1856    use nautilus_common::live::runner::replace_data_event_sender;
1857    use nautilus_core::UUID4;
1858    use nautilus_model::{
1859        data::{
1860            BarSpecification, BarType, FundingRateUpdate, IndexPriceUpdate, MarkPriceUpdate,
1861            TradeTick,
1862        },
1863        enums::{AggregationSource, AggressorSide, BarAggregation, PriceType},
1864        identifiers::{InstrumentId, Symbol, TradeId},
1865        instruments::{CryptoPerpetual, CurrencyPair},
1866        types::{Currency, Price, Quantity},
1867    };
1868    use rstest::rstest;
1869    use rust_decimal::Decimal;
1870
1871    use super::{
1872        limits::{LIGHTER_BOOK_ORDERS_MAX_LIMIT, LIGHTER_RECENT_TRADES_MAX_LIMIT},
1873        market_stats::{MarketStatsFlags, MarketStatsSubscription},
1874        *,
1875    };
1876    use crate::{
1877        common::{
1878            consts::LIGHTER_VENUE,
1879            enums::{LighterFundingResolution, LighterProductType},
1880        },
1881        http::query::{LighterFundingsQuery, LighterRecentTradesQuery},
1882    };
1883
1884    struct DropSignal(Option<tokio::sync::oneshot::Sender<()>>);
1885
1886    impl Drop for DropSignal {
1887        fn drop(&mut self) {
1888            if let Some(sender) = self.0.take() {
1889                let _ = sender.send(());
1890            }
1891        }
1892    }
1893
1894    const HTTP_ORDER_BOOK_DETAILS: &str =
1895        include_str!("../../test_data/http_order_book_details.json");
1896    const HTTP_FUNDINGS: &str = include_str!("../../test_data/http_fundings.json");
1897    const HTTP_RECENT_TRADES: &str = include_str!("../../test_data/http_recent_trades.json");
1898    const HTTP_RECENT_TRADES_NULL: &str =
1899        include_str!("../../test_data/http_recent_trades_null.json");
1900    const HTTP_RECENT_TRADES_UNORDERED: &str =
1901        include_str!("../../test_data/http_recent_trades_unordered.json");
1902    const PRIVATE_KEY_HEX: &str =
1903        "0b8e0f63c24d8baacd9d29ad4e9a4b73c4a8d2bb8b16dc4fa9d7c2e1d3a8b1f0e8d3a4c5b6e7f001";
1904
1905    #[rstest]
1906    #[case::none_defaults_to_cap(None, LIGHTER_BOOK_ORDERS_MAX_LIMIT)]
1907    #[case::below_cap_passes_through(Some(10), 10)]
1908    #[case::at_cap_passes_through(
1909        Some(LIGHTER_BOOK_ORDERS_MAX_LIMIT as usize),
1910        LIGHTER_BOOK_ORDERS_MAX_LIMIT
1911    )]
1912    #[case::above_cap_clamps(Some(500), LIGHTER_BOOK_ORDERS_MAX_LIMIT)]
1913    #[case::usize_max_clamps(Some(usize::MAX), LIGHTER_BOOK_ORDERS_MAX_LIMIT)]
1914    fn test_clamp_book_snapshot_limit(#[case] depth: Option<usize>, #[case] expected: u16) {
1915        let depth = depth.map(|n| NonZeroUsize::new(n).expect("non-zero"));
1916        assert_eq!(clamp_book_snapshot_limit(depth), expected);
1917    }
1918
1919    #[rstest]
1920    #[case::none_defaults_to_cap(None, LIGHTER_RECENT_TRADES_MAX_LIMIT)]
1921    #[case::below_cap_passes_through(Some(10), 10)]
1922    #[case::at_cap_passes_through(
1923        Some(LIGHTER_RECENT_TRADES_MAX_LIMIT as usize),
1924        LIGHTER_RECENT_TRADES_MAX_LIMIT
1925    )]
1926    #[case::above_cap_clamps(Some(500), LIGHTER_RECENT_TRADES_MAX_LIMIT)]
1927    #[case::usize_max_clamps(Some(usize::MAX), LIGHTER_RECENT_TRADES_MAX_LIMIT)]
1928    fn test_clamp_recent_trades_limit(#[case] limit: Option<usize>, #[case] expected: u16) {
1929        let limit = limit.map(|n| NonZeroUsize::new(n).expect("non-zero"));
1930        assert_eq!(clamp_recent_trades_limit(limit), expected);
1931    }
1932
1933    #[rstest]
1934    fn test_new_uses_readonly_websocket_url() {
1935        let client = create_data_client_for_test();
1936
1937        assert_eq!(
1938            client.ws_client.url(),
1939            "wss://mainnet.zklighter.elliot.ai/stream?readonly=true",
1940        );
1941    }
1942
1943    #[rstest]
1944    fn test_validate_book_deltas_accepts_l2_mbp() {
1945        assert!(validate_book_deltas_subscription(BookType::L2_MBP).is_ok());
1946    }
1947
1948    #[rstest]
1949    #[case(BookType::L1_MBP)]
1950    #[case(BookType::L3_MBO)]
1951    fn test_validate_book_deltas_rejects_other_book_types(#[case] book_type: BookType) {
1952        let err = validate_book_deltas_subscription(book_type).unwrap_err();
1953        assert!(
1954            err.to_string().contains("L2_MBP"),
1955            "expected error to cite L2_MBP, was: {err}",
1956        );
1957    }
1958
1959    #[rstest]
1960    fn test_validate_book_depth_accepts_l2_mbp() {
1961        assert!(validate_book_depth_subscription(BookType::L2_MBP).is_ok());
1962    }
1963
1964    #[rstest]
1965    #[case(BookType::L1_MBP)]
1966    #[case(BookType::L3_MBO)]
1967    fn test_validate_book_depth_rejects_other_book_types(#[case] book_type: BookType) {
1968        let err = validate_book_depth_subscription(book_type).unwrap_err();
1969        assert!(
1970            err.to_string().contains("depth"),
1971            "expected error to cite depth, was: {err}",
1972        );
1973    }
1974
1975    #[rstest]
1976    #[case(LighterMarketStatus::Active, MarketStatusAction::Trading)]
1977    #[case(
1978        LighterMarketStatus::Inactive,
1979        MarketStatusAction::NotAvailableForTrading
1980    )]
1981    fn test_lighter_market_status_action(
1982        #[case] status: LighterMarketStatus,
1983        #[case] expected: MarketStatusAction,
1984    ) {
1985        assert_eq!(lighter_market_status_action(status).unwrap(), expected);
1986    }
1987
1988    #[rstest]
1989    #[case(LighterMarketStatus::InSettlement, "in-settlement")]
1990    #[case(LighterMarketStatus::WaitingForSettlement, "waiting-for-settlement")]
1991    #[case(LighterMarketStatus::Settled, "settled")]
1992    #[case(LighterMarketStatus::Unknown, "unknown")]
1993    fn test_lighter_market_status_action_rejects_unmapped_status(
1994        #[case] status: LighterMarketStatus,
1995        #[case] label: &str,
1996    ) {
1997        let err = lighter_market_status_action(status).unwrap_err();
1998
1999        assert_eq!(
2000            err.to_string(),
2001            format!("Lighter market status `{label}` has no Nautilus market status action"),
2002        );
2003    }
2004
2005    #[rstest]
2006    fn test_emit_lighter_instrument_status_skips_unmapped_status() {
2007        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
2008        let sender = sender.into();
2009        let instrument_id = InstrumentId::from("ETH-PERP.LIGHTER");
2010
2011        emit_lighter_instrument_status(
2012            &sender,
2013            instrument_id,
2014            LighterMarketStatus::Unknown,
2015            UnixNanos::from(1),
2016            UnixNanos::from(2),
2017        );
2018        emit_lighter_instrument_status(
2019            &sender,
2020            instrument_id,
2021            LighterMarketStatus::Inactive,
2022            UnixNanos::from(3),
2023            UnixNanos::from(4),
2024        );
2025
2026        let DataEvent::Data(Data::InstrumentStatus(status)) = receiver.try_recv().unwrap() else {
2027            panic!("expected instrument status");
2028        };
2029
2030        assert_eq!(status.action, MarketStatusAction::NotAvailableForTrading);
2031        assert_eq!(status.ts_event, UnixNanos::from(3));
2032        assert!(receiver.try_recv().is_err());
2033    }
2034
2035    #[tokio::test]
2036    async fn test_subscribe_instrument_status_replays_cached_status() {
2037        let (mut client, mut receiver) = create_data_client_with_receiver_for_test();
2038        let instrument_id = cache_test_instrument(&client, 0, "ETH", LighterProductType::Perp);
2039        cache_lighter_instrument_status(
2040            &client.instrument_statuses,
2041            instrument_id,
2042            LighterMarketStatus::Active,
2043        );
2044
2045        DataClient::subscribe_instrument_status(
2046            &mut client,
2047            SubscribeInstrumentStatus::new(
2048                instrument_id,
2049                Some(ClientId::new("LIGHTER")),
2050                None,
2051                UUID4::new(),
2052                UnixNanos::default(),
2053                None,
2054                None,
2055            ),
2056        )
2057        .unwrap();
2058
2059        let event = receiver.recv().await.expect("instrument status event");
2060        match event {
2061            DataEvent::Data(Data::InstrumentStatus(status)) => {
2062                assert_eq!(status.instrument_id, instrument_id);
2063                assert_eq!(status.action, MarketStatusAction::Trading);
2064                assert_eq!(status.is_trading, Some(true));
2065            }
2066            event => panic!("expected instrument status, was {event:?}"),
2067        }
2068    }
2069
2070    #[tokio::test]
2071    async fn test_subscribe_instrument_status_fetches_when_cache_is_empty() {
2072        let base_url = spawn_order_book_details_server().await;
2073        let config = LighterDataClientConfig {
2074            base_url_http: Some(base_url),
2075            ..Default::default()
2076        };
2077        let (mut client, mut receiver) =
2078            create_data_client_with_receiver_and_config_for_test(config);
2079        let instrument_id = client.registry.insert(0, "ETH", LighterProductType::Perp);
2080
2081        DataClient::subscribe_instrument_status(
2082            &mut client,
2083            SubscribeInstrumentStatus::new(
2084                instrument_id,
2085                Some(ClientId::new("LIGHTER")),
2086                None,
2087                UUID4::new(),
2088                UnixNanos::default(),
2089                None,
2090                None,
2091            ),
2092        )
2093        .unwrap();
2094
2095        let event = tokio::time::timeout(Duration::from_secs(2), receiver.recv())
2096            .await
2097            .expect("instrument status response")
2098            .expect("instrument status event");
2099
2100        match event {
2101            DataEvent::Data(Data::InstrumentStatus(status)) => {
2102                assert_eq!(status.instrument_id, instrument_id);
2103                assert_eq!(status.action, MarketStatusAction::Trading);
2104                assert_eq!(status.is_trading, Some(true));
2105            }
2106            event => panic!("expected instrument status, was {event:?}"),
2107        }
2108        assert!(client.instruments.get_cloned(&instrument_id).is_some());
2109        assert_eq!(
2110            client
2111                .instrument_statuses
2112                .get(&instrument_id)
2113                .map(|status| *status),
2114            Some(LighterMarketStatus::Active),
2115        );
2116    }
2117
2118    #[tokio::test]
2119    async fn test_market_stats_subscriptions_share_perp_channel_until_last_unsub() {
2120        let mut client = create_data_client_for_test();
2121        // Prevent the unconnected test client from asynchronously rolling back local flags
2122        client.cancellation_token.cancel();
2123        let instrument_id = cache_test_instrument(&client, 0, "ETH", LighterProductType::Perp);
2124
2125        DataClient::subscribe_mark_prices(
2126            &mut client,
2127            SubscribeMarkPrices::new(
2128                instrument_id,
2129                Some(ClientId::new("LIGHTER")),
2130                None,
2131                UUID4::new(),
2132                UnixNanos::default(),
2133                None,
2134                None,
2135            ),
2136        )
2137        .unwrap();
2138        DataClient::subscribe_index_prices(
2139            &mut client,
2140            SubscribeIndexPrices::new(
2141                instrument_id,
2142                Some(ClientId::new("LIGHTER")),
2143                None,
2144                UUID4::new(),
2145                UnixNanos::default(),
2146                None,
2147                None,
2148            ),
2149        )
2150        .unwrap();
2151        DataClient::subscribe_funding_rates(
2152            &mut client,
2153            SubscribeFundingRates::new(
2154                instrument_id,
2155                Some(ClientId::new("LIGHTER")),
2156                None,
2157                UUID4::new(),
2158                UnixNanos::default(),
2159                None,
2160                None,
2161            ),
2162        )
2163        .unwrap();
2164
2165        let subscription = client
2166            .market_stats_subscriptions
2167            .get(&instrument_id)
2168            .expect("market stats subscription");
2169        assert_eq!(
2170            subscription.flags,
2171            MarketStatsFlags {
2172                mark_price: true,
2173                index_price: true,
2174                funding_rate: true,
2175            },
2176        );
2177        assert!(matches!(
2178            subscription.channel,
2179            LighterWsChannel::MarketStats(LighterMarketSelection::Market(0)),
2180        ));
2181        drop(subscription);
2182        assert!(
2183            client
2184                .market_stats_subscription_generations
2185                .contains_key(&instrument_id),
2186        );
2187
2188        DataClient::unsubscribe_mark_prices(
2189            &mut client,
2190            &UnsubscribeMarkPrices::new(
2191                instrument_id,
2192                Some(ClientId::new("LIGHTER")),
2193                None,
2194                UUID4::new(),
2195                UnixNanos::default(),
2196                None,
2197                None,
2198            ),
2199        )
2200        .unwrap();
2201        assert_eq!(
2202            client
2203                .market_stats_subscriptions
2204                .get(&instrument_id)
2205                .expect("index and funding still active")
2206                .flags,
2207            MarketStatsFlags {
2208                index_price: true,
2209                funding_rate: true,
2210                ..Default::default()
2211            },
2212        );
2213
2214        DataClient::unsubscribe_index_prices(
2215            &mut client,
2216            &UnsubscribeIndexPrices::new(
2217                instrument_id,
2218                Some(ClientId::new("LIGHTER")),
2219                None,
2220                UUID4::new(),
2221                UnixNanos::default(),
2222                None,
2223                None,
2224            ),
2225        )
2226        .unwrap();
2227        assert_eq!(
2228            client
2229                .market_stats_subscriptions
2230                .get(&instrument_id)
2231                .expect("funding still active")
2232                .flags,
2233            MarketStatsFlags {
2234                funding_rate: true,
2235                ..Default::default()
2236            },
2237        );
2238
2239        DataClient::unsubscribe_funding_rates(
2240            &mut client,
2241            &UnsubscribeFundingRates::new(
2242                instrument_id,
2243                Some(ClientId::new("LIGHTER")),
2244                None,
2245                UUID4::new(),
2246                UnixNanos::default(),
2247                None,
2248                None,
2249            ),
2250        )
2251        .unwrap();
2252        assert!(
2253            !client
2254                .market_stats_subscriptions
2255                .contains_key(&instrument_id)
2256        );
2257        assert!(
2258            !client
2259                .market_stats_subscription_generations
2260                .contains_key(&instrument_id),
2261        );
2262    }
2263
2264    #[rstest]
2265    fn test_market_stats_ws_forwarding_requires_matching_subscription() {
2266        let subscriptions = DashMap::new();
2267        let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
2268        let instrument_id = InstrumentId::new(Symbol::new("ETH-PERP"), *LIGHTER_VENUE);
2269        let other_instrument_id = InstrumentId::new(Symbol::new("BTC-PERP"), *LIGHTER_VENUE);
2270
2271        subscriptions.insert(
2272            instrument_id,
2273            MarketStatsSubscription {
2274                channel: LighterWsChannel::MarketStats(LighterMarketSelection::Market(0)),
2275                flags: MarketStatsFlags {
2276                    mark_price: true,
2277                    index_price: true,
2278                    funding_rate: true,
2279                },
2280            },
2281        );
2282
2283        assert!(emit_market_stats_ws_message(
2284            &sender.clone().into(),
2285            &subscriptions,
2286            &NautilusWsMessage::MarkPrice(MarkPriceUpdate::new(
2287                instrument_id,
2288                Price::from("2000.00"),
2289                UnixNanos::from(10),
2290                UnixNanos::from(1),
2291            )),
2292        ));
2293        assert!(emit_market_stats_ws_message(
2294            &sender.clone().into(),
2295            &subscriptions,
2296            &NautilusWsMessage::IndexPrice(IndexPriceUpdate::new(
2297                instrument_id,
2298                Price::from("1999.50"),
2299                UnixNanos::from(11),
2300                UnixNanos::from(1),
2301            )),
2302        ));
2303        assert!(emit_market_stats_ws_message(
2304            &sender.clone().into(),
2305            &subscriptions,
2306            &NautilusWsMessage::FundingRate(FundingRateUpdate::new(
2307                instrument_id,
2308                Decimal::new(12, 6),
2309                None,
2310                Some(UnixNanos::from(100)),
2311                UnixNanos::from(12),
2312                UnixNanos::from(1),
2313            )),
2314        ));
2315
2316        match receiver.try_recv().unwrap() {
2317            DataEvent::Data(Data::MarkPrice(update)) => {
2318                assert_eq!(update.instrument_id, instrument_id);
2319                assert_eq!(update.value, Price::from("2000.00"));
2320            }
2321            event => panic!("expected mark price update, was {event:?}"),
2322        }
2323
2324        match receiver.try_recv().unwrap() {
2325            DataEvent::Data(Data::IndexPrice(update)) => {
2326                assert_eq!(update.instrument_id, instrument_id);
2327                assert_eq!(update.value, Price::from("1999.50"));
2328            }
2329            event => panic!("expected index price update, was {event:?}"),
2330        }
2331
2332        match receiver.try_recv().unwrap() {
2333            DataEvent::Data(Data::FundingRate(update)) => {
2334                assert_eq!(update.instrument_id, instrument_id);
2335                assert_eq!(update.rate, Decimal::new(12, 6));
2336            }
2337            event => panic!("expected funding rate update, was {event:?}"),
2338        }
2339
2340        assert!(!emit_market_stats_ws_message(
2341            &sender.into(),
2342            &subscriptions,
2343            &NautilusWsMessage::MarkPrice(MarkPriceUpdate::new(
2344                other_instrument_id,
2345                Price::from("1.00"),
2346                UnixNanos::from(13),
2347                UnixNanos::from(1),
2348            )),
2349        ));
2350        assert!(receiver.try_recv().is_err());
2351    }
2352
2353    #[rstest]
2354    fn test_index_market_stats_channel_uses_spot_stream_for_spot_instrument() {
2355        let client = create_data_client_for_test();
2356        let instrument_id = cache_test_instrument(&client, 2048, "ETH", LighterProductType::Spot);
2357
2358        let channel = client.index_market_stats_channel(instrument_id).unwrap();
2359
2360        assert!(matches!(
2361            channel,
2362            LighterWsChannel::SpotMarketStats(LighterMarketSelection::Market(2048)),
2363        ));
2364    }
2365
2366    #[rstest]
2367    fn test_index_market_stats_channel_routes_widened_ids_by_instrument_type() {
2368        let client = create_data_client_for_test();
2369        let perp_id = cache_test_instrument(&client, 40_000, "ETH", LighterProductType::Perp);
2370        let spot_id = cache_test_instrument(&client, 50_000, "ETH", LighterProductType::Spot);
2371
2372        let perp_channel = client.index_market_stats_channel(perp_id).unwrap();
2373        let spot_channel = client.index_market_stats_channel(spot_id).unwrap();
2374
2375        assert!(matches!(
2376            perp_channel,
2377            LighterWsChannel::MarketStats(LighterMarketSelection::Market(40_000)),
2378        ));
2379        assert!(matches!(
2380            spot_channel,
2381            LighterWsChannel::SpotMarketStats(LighterMarketSelection::Market(50_000)),
2382        ));
2383    }
2384
2385    #[rstest]
2386    fn test_mark_price_channel_rejects_spot_instrument() {
2387        let client = create_data_client_for_test();
2388        let instrument_id = cache_test_instrument(&client, 2048, "ETH", LighterProductType::Spot);
2389
2390        let err = client
2391            .perp_market_stats_channel(instrument_id, "mark price")
2392            .unwrap_err();
2393
2394        assert!(
2395            err.to_string()
2396                .contains("mark price subscriptions require a perpetual instrument"),
2397        );
2398    }
2399
2400    #[rstest]
2401    fn test_request_bars_rejects_unsupported_bar_type() {
2402        let client = create_data_client_for_test();
2403        let request = RequestBars::new(
2404            unsupported_three_minute_bar_type(),
2405            None,
2406            None,
2407            None,
2408            Some(ClientId::new("LIGHTER")),
2409            UUID4::new(),
2410            UnixNanos::default(),
2411            None,
2412        );
2413
2414        let err = DataClient::request_bars(&client, request).unwrap_err();
2415
2416        assert_eq!(err.to_string(), "unsupported Lighter candle minute step: 3");
2417    }
2418
2419    #[rstest]
2420    fn test_subscribe_bars_rejects_unsupported_bar_type() {
2421        let mut client = create_data_client_for_test();
2422        let subscription = SubscribeBars::new(
2423            unsupported_three_minute_bar_type(),
2424            Some(ClientId::new("LIGHTER")),
2425            None,
2426            UUID4::new(),
2427            UnixNanos::default(),
2428            None,
2429            None,
2430        );
2431
2432        let err = DataClient::subscribe_bars(&mut client, subscription).unwrap_err();
2433
2434        assert_eq!(err.to_string(), "unsupported Lighter candle minute step: 3");
2435    }
2436
2437    #[rstest]
2438    fn test_subscribe_bars_accepts_ws_streamable_resolution() {
2439        let mut client = create_data_client_for_test();
2440        let instrument_id = cache_test_instrument(&client, 0, "ETH", LighterProductType::Perp);
2441        let bar_type = BarType::new(
2442            instrument_id,
2443            BarSpecification::new(1, BarAggregation::Minute, PriceType::Last),
2444            AggregationSource::External,
2445        );
2446        let subscription = SubscribeBars::new(
2447            bar_type,
2448            Some(ClientId::new("LIGHTER")),
2449            None,
2450            UUID4::new(),
2451            UnixNanos::default(),
2452            None,
2453            None,
2454        );
2455
2456        DataClient::subscribe_bars(&mut client, subscription).unwrap();
2457    }
2458
2459    #[rstest]
2460    fn test_subscribe_bars_missing_cached_instrument_returns_lookup_error() {
2461        let mut client = create_data_client_for_test();
2462        let instrument_id = InstrumentId::new(Symbol::new("ETH-PERP"), *LIGHTER_VENUE);
2463        let bar_type = BarType::new(
2464            instrument_id,
2465            BarSpecification::new(1, BarAggregation::Minute, PriceType::Last),
2466            AggregationSource::External,
2467        );
2468        let subscription = SubscribeBars::new(
2469            bar_type,
2470            Some(ClientId::new("LIGHTER")),
2471            None,
2472            UUID4::new(),
2473            UnixNanos::default(),
2474            None,
2475            None,
2476        );
2477
2478        let err = DataClient::subscribe_bars(&mut client, subscription).unwrap_err();
2479
2480        assert_eq!(
2481            err.to_string(),
2482            InstrumentLookupError::not_found(instrument_id).to_string()
2483        );
2484    }
2485
2486    #[rstest]
2487    fn test_subscribe_bars_rejects_one_week_with_ws_message() {
2488        let mut client = create_data_client_for_test();
2489        let instrument_id = cache_test_instrument(&client, 0, "ETH", LighterProductType::Perp);
2490        let bar_type = BarType::new(
2491            instrument_id,
2492            BarSpecification::new(1, BarAggregation::Week, PriceType::Last),
2493            AggregationSource::External,
2494        );
2495        let subscription = SubscribeBars::new(
2496            bar_type,
2497            Some(ClientId::new("LIGHTER")),
2498            None,
2499            UUID4::new(),
2500            UnixNanos::default(),
2501            None,
2502            None,
2503        );
2504
2505        let err = DataClient::subscribe_bars(&mut client, subscription).unwrap_err();
2506
2507        assert!(
2508            err.to_string().contains("does not offer")
2509                && err.to_string().contains("candle WebSocket stream"),
2510            "expected WS-streamable rejection, was: {err}",
2511        );
2512    }
2513
2514    #[rstest]
2515    fn test_unsubscribe_bars_returns_ok_for_unsupported_bar_type() {
2516        let mut client = create_data_client_for_test();
2517        let unsubscription = UnsubscribeBars::new(
2518            unsupported_three_minute_bar_type(),
2519            Some(ClientId::new("LIGHTER")),
2520            None,
2521            UUID4::new(),
2522            UnixNanos::default(),
2523            None,
2524            None,
2525        );
2526
2527        DataClient::unsubscribe_bars(&mut client, &unsubscription).unwrap();
2528    }
2529
2530    #[rstest]
2531    fn test_subscribe_book_depth_rejects_unsupported_book_type() {
2532        let mut client = create_data_client_for_test();
2533        let instrument_id = InstrumentId::new(Symbol::new("ETH-PERP"), *LIGHTER_VENUE);
2534        let subscription = SubscribeBookDepth::new(
2535            instrument_id,
2536            BookType::L1_MBP,
2537            Some(ClientId::new("LIGHTER")),
2538            None,
2539            UUID4::new(),
2540            UnixNanos::default(),
2541            None,
2542            false,
2543            None,
2544            None,
2545        );
2546
2547        let err = DataClient::subscribe_book_depth(&mut client, subscription).unwrap_err();
2548
2549        assert!(err.to_string().contains("L2_MBP"));
2550    }
2551
2552    #[rstest]
2553    fn test_request_quotes_rejects_unsupported_rest_quotes() {
2554        let client = create_data_client_for_test();
2555        let instrument_id = InstrumentId::new(Symbol::new("ETH-PERP"), *LIGHTER_VENUE);
2556        let request = RequestQuotes::new(
2557            instrument_id,
2558            None,
2559            None,
2560            None,
2561            Some(ClientId::new("LIGHTER")),
2562            UUID4::new(),
2563            UnixNanos::default(),
2564            None,
2565        );
2566
2567        let err = DataClient::request_quotes(&client, request).unwrap_err();
2568
2569        assert!(
2570            err.to_string()
2571                .contains("does not support historical quote requests"),
2572        );
2573    }
2574
2575    #[rstest]
2576    fn test_request_book_depth_rejects_unsupported_rest_depth() {
2577        let client = create_data_client_for_test();
2578        let instrument_id = InstrumentId::new(Symbol::new("ETH-PERP"), *LIGHTER_VENUE);
2579        let request = RequestBookDepth::new(
2580            instrument_id,
2581            None,
2582            None,
2583            None,
2584            NonZeroUsize::new(10),
2585            Some(ClientId::new("LIGHTER")),
2586            UUID4::new(),
2587            UnixNanos::default(),
2588            None,
2589        );
2590
2591        let err = DataClient::request_book_depth(&client, request).unwrap_err();
2592
2593        assert!(
2594            err.to_string()
2595                .contains("does not support historical order book depth requests"),
2596        );
2597    }
2598
2599    #[rstest]
2600    fn test_request_funding_rates_rejects_spot_instrument() {
2601        let client = create_data_client_for_test();
2602        let instrument_id = cache_test_instrument(&client, 2048, "ETH", LighterProductType::Spot);
2603        let request = RequestFundingRates::new(
2604            instrument_id,
2605            None,
2606            None,
2607            None,
2608            Some(ClientId::new("LIGHTER")),
2609            UUID4::new(),
2610            UnixNanos::default(),
2611            None,
2612        );
2613
2614        let err = DataClient::request_funding_rates(&client, request).unwrap_err();
2615
2616        assert!(
2617            err.to_string()
2618                .contains("funding-rate requests require a perpetual instrument"),
2619        );
2620    }
2621
2622    #[tokio::test]
2623    async fn test_request_funding_rates_emits_response() {
2624        let base_url = spawn_fundings_server().await;
2625        let config = LighterDataClientConfig {
2626            base_url_http: Some(base_url),
2627            ..Default::default()
2628        };
2629        let (client, mut receiver) = create_data_client_with_receiver_and_config_for_test(config);
2630        let instrument_id = cache_test_instrument(&client, 0, "ETH", LighterProductType::Perp);
2631        let start = Timestamp::from_second(1_778_702_400).unwrap();
2632        let end = Timestamp::from_second(1_778_706_000).unwrap();
2633        let request = RequestFundingRates::new(
2634            instrument_id,
2635            Some(start),
2636            Some(end),
2637            NonZeroUsize::new(2),
2638            Some(ClientId::new("LIGHTER")),
2639            UUID4::new(),
2640            UnixNanos::default(),
2641            None,
2642        );
2643
2644        DataClient::request_funding_rates(&client, request).unwrap();
2645
2646        let event = tokio::time::timeout(Duration::from_secs(2), receiver.recv())
2647            .await
2648            .expect("funding rates response")
2649            .expect("funding rates event");
2650
2651        match event {
2652            DataEvent::Response(DataResponse::FundingRates(response)) => {
2653                assert_eq!(response.instrument_id, instrument_id);
2654                assert_eq!(response.data.len(), 2);
2655                assert_eq!(response.data[0].rate, Decimal::new(12, 6));
2656                assert_eq!(response.data[0].interval, Some(60));
2657                assert_eq!(
2658                    response.data[0].ts_event,
2659                    UnixNanos::from(1_778_702_400_000_000_000)
2660                );
2661                assert_eq!(response.data[1].rate, Decimal::new(-2, 6));
2662                assert_eq!(response.data[1].interval, Some(60));
2663            }
2664            event => panic!("expected funding rates response, was {event:?}"),
2665        }
2666    }
2667
2668    #[tokio::test]
2669    async fn test_request_trades_uses_recent_trades_endpoint() {
2670        let base_url = spawn_trades_server().await;
2671        let config = LighterDataClientConfig {
2672            base_url_http: Some(base_url),
2673            ..Default::default()
2674        };
2675        let (client, mut receiver) = create_data_client_with_receiver_and_config_for_test(config);
2676        let instrument_id = cache_test_instrument(&client, 0, "ETH", LighterProductType::Perp);
2677        let start = Timestamp::from_second(1_700_000_000).unwrap();
2678        let request = RequestTrades::new(
2679            instrument_id,
2680            Some(start),
2681            None,
2682            NonZeroUsize::new(50),
2683            Some(ClientId::new("LIGHTER")),
2684            UUID4::new(),
2685            UnixNanos::default(),
2686            None,
2687        );
2688
2689        DataClient::request_trades(&client, request).unwrap();
2690
2691        let event = tokio::time::timeout(Duration::from_secs(2), receiver.recv())
2692            .await
2693            .expect("trades response")
2694            .expect("trades event");
2695
2696        match event {
2697            DataEvent::Response(DataResponse::Trades(response)) => {
2698                assert_eq!(response.instrument_ids, vec![instrument_id]);
2699                assert_eq!(response.data.len(), 1);
2700                let tick = &response.data[0];
2701                assert_eq!(tick.instrument_id, instrument_id);
2702                assert_eq!(tick.price, Price::from("2361.31"));
2703                assert_eq!(tick.size, Quantity::from("0.0005"));
2704                assert_eq!(tick.aggressor_side, AggressorSide::Sell);
2705                assert_eq!(tick.trade_id.to_string(), "19211490282");
2706            }
2707            event => panic!("expected trades response, was {event:?}"),
2708        }
2709    }
2710
2711    #[tokio::test]
2712    async fn test_request_trades_clamps_limit_to_venue_cap() {
2713        let base_url = spawn_trades_server_with_response_and_limit(
2714            HTTP_RECENT_TRADES,
2715            LIGHTER_RECENT_TRADES_MAX_LIMIT,
2716        )
2717        .await;
2718        let config = LighterDataClientConfig {
2719            base_url_http: Some(base_url),
2720            ..Default::default()
2721        };
2722        let (client, mut receiver) = create_data_client_with_receiver_and_config_for_test(config);
2723        let instrument_id = cache_test_instrument(&client, 0, "ETH", LighterProductType::Perp);
2724        let request = RequestTrades::new(
2725            instrument_id,
2726            None,
2727            None,
2728            NonZeroUsize::new(usize::from(LIGHTER_RECENT_TRADES_MAX_LIMIT) + 1),
2729            Some(ClientId::new("LIGHTER")),
2730            UUID4::new(),
2731            UnixNanos::default(),
2732            None,
2733        );
2734
2735        DataClient::request_trades(&client, request).unwrap();
2736
2737        let event = tokio::time::timeout(Duration::from_secs(2), receiver.recv())
2738            .await
2739            .expect("trades response")
2740            .expect("trades event");
2741
2742        assert!(
2743            matches!(event, DataEvent::Response(DataResponse::Trades(_))),
2744            "expected trades response, was {event:?}",
2745        );
2746    }
2747
2748    #[tokio::test]
2749    async fn test_request_trades_emits_empty_response_for_null_recent_trades() {
2750        let base_url = spawn_trades_server_with_response(HTTP_RECENT_TRADES_NULL).await;
2751        let config = LighterDataClientConfig {
2752            base_url_http: Some(base_url),
2753            ..Default::default()
2754        };
2755        let (client, mut receiver) = create_data_client_with_receiver_and_config_for_test(config);
2756        let instrument_id = cache_test_instrument(&client, 0, "ETH", LighterProductType::Perp);
2757        let start = Timestamp::from_second(1_700_000_000).unwrap();
2758        let request = RequestTrades::new(
2759            instrument_id,
2760            Some(start),
2761            None,
2762            NonZeroUsize::new(50),
2763            Some(ClientId::new("LIGHTER")),
2764            UUID4::new(),
2765            UnixNanos::default(),
2766            None,
2767        );
2768
2769        DataClient::request_trades(&client, request).unwrap();
2770
2771        let event = tokio::time::timeout(Duration::from_secs(2), receiver.recv())
2772            .await
2773            .expect("trades response")
2774            .expect("trades event");
2775
2776        match event {
2777            DataEvent::Response(DataResponse::Trades(response)) => {
2778                assert_eq!(response.instrument_ids, vec![instrument_id]);
2779                assert!(response.data.is_empty());
2780            }
2781            event => panic!("expected trades response, was {event:?}"),
2782        }
2783    }
2784
2785    #[tokio::test]
2786    async fn test_request_trades_filters_recent_trades_to_requested_range() {
2787        let base_url = spawn_trades_server().await;
2788        let config = LighterDataClientConfig {
2789            base_url_http: Some(base_url),
2790            ..Default::default()
2791        };
2792        let (client, mut receiver) = create_data_client_with_receiver_and_config_for_test(config);
2793        let instrument_id = cache_test_instrument(&client, 0, "ETH", LighterProductType::Perp);
2794        let end = Timestamp::from_second(1_700_000_000).unwrap();
2795        let request = RequestTrades::new(
2796            instrument_id,
2797            None,
2798            Some(end),
2799            NonZeroUsize::new(50),
2800            Some(ClientId::new("LIGHTER")),
2801            UUID4::new(),
2802            UnixNanos::default(),
2803            None,
2804        );
2805
2806        DataClient::request_trades(&client, request).unwrap();
2807
2808        let event = tokio::time::timeout(Duration::from_secs(2), receiver.recv())
2809            .await
2810            .expect("trades response")
2811            .expect("trades event");
2812
2813        match event {
2814            DataEvent::Response(DataResponse::Trades(response)) => {
2815                assert_eq!(response.instrument_ids, vec![instrument_id]);
2816                assert!(response.data.is_empty());
2817            }
2818            event => panic!("expected trades response, was {event:?}"),
2819        }
2820    }
2821
2822    #[tokio::test]
2823    async fn test_request_trades_returns_recent_trades_in_timestamp_order() {
2824        let base_url = spawn_trades_server_with_response(HTTP_RECENT_TRADES_UNORDERED).await;
2825        let config = LighterDataClientConfig {
2826            base_url_http: Some(base_url),
2827            ..Default::default()
2828        };
2829        let (client, mut receiver) = create_data_client_with_receiver_and_config_for_test(config);
2830        let instrument_id = cache_test_instrument(&client, 0, "ETH", LighterProductType::Perp);
2831        let start = Timestamp::from_millisecond(1_777_945_103_092).unwrap();
2832        let end = Timestamp::from_millisecond(1_777_945_103_094).unwrap();
2833        let request = RequestTrades::new(
2834            instrument_id,
2835            Some(start),
2836            Some(end),
2837            NonZeroUsize::new(50),
2838            Some(ClientId::new("LIGHTER")),
2839            UUID4::new(),
2840            UnixNanos::default(),
2841            None,
2842        );
2843
2844        DataClient::request_trades(&client, request).unwrap();
2845
2846        let event = tokio::time::timeout(Duration::from_secs(2), receiver.recv())
2847            .await
2848            .expect("trades response")
2849            .expect("trades event");
2850
2851        match event {
2852            DataEvent::Response(DataResponse::Trades(response)) => {
2853                assert_eq!(response.instrument_ids, vec![instrument_id]);
2854                assert_eq!(
2855                    response
2856                        .data
2857                        .iter()
2858                        .map(|trade| trade.trade_id.to_string())
2859                        .collect::<Vec<_>>(),
2860                    vec!["19211490282", "19211490283", "19211490284"],
2861                );
2862                assert_eq!(
2863                    response
2864                        .data
2865                        .iter()
2866                        .map(|trade| trade.ts_event.as_u64())
2867                        .collect::<Vec<_>>(),
2868                    vec![
2869                        1_777_945_103_092_000_000,
2870                        1_777_945_103_093_000_000,
2871                        1_777_945_103_094_000_000,
2872                    ],
2873                );
2874            }
2875            event => panic!("expected trades response, was {event:?}"),
2876        }
2877    }
2878
2879    #[rstest]
2880    fn test_retain_trade_ticks_in_range_sorts_ascending() {
2881        let instrument_id = InstrumentId::new(Symbol::new("ETH-PERP"), *LIGHTER_VENUE);
2882        let tick = |ts_event, trade_id| {
2883            TradeTick::new(
2884                instrument_id,
2885                Price::from("1.0"),
2886                Quantity::from("1.0"),
2887                AggressorSide::Buy,
2888                TradeId::new(trade_id),
2889                UnixNanos::from(ts_event),
2890                UnixNanos::from(ts_event + 1),
2891            )
2892        };
2893        let mut trades = vec![tick(4, "4"), tick(1, "1"), tick(3, "3"), tick(2, "2")];
2894
2895        retain_trade_ticks_in_range(
2896            &mut trades,
2897            Some(UnixNanos::from(2)),
2898            Some(UnixNanos::from(4)),
2899        );
2900
2901        assert_eq!(
2902            trades
2903                .iter()
2904                .map(|trade| trade.ts_event.as_u64())
2905                .collect::<Vec<_>>(),
2906            vec![2, 3, 4],
2907        );
2908    }
2909
2910    #[tokio::test]
2911    async fn test_spawn_instrument_refresh_skipped_when_interval_zero() {
2912        let config = LighterDataClientConfig {
2913            update_instruments_interval_mins: 0,
2914            ..Default::default()
2915        };
2916        let (client, _receiver) = create_data_client_with_receiver_and_config_for_test(config);
2917
2918        assert!(client.tasks.is_empty());
2919        client
2920            .spawn_instrument_refresh()
2921            .expect("instrument refresh remains disabled");
2922        assert!(client.tasks.is_empty());
2923    }
2924
2925    #[tokio::test]
2926    async fn test_spawn_instrument_refresh_registers_task() {
2927        let config = LighterDataClientConfig {
2928            update_instruments_interval_mins: 60,
2929            ..Default::default()
2930        };
2931        let (mut client, _receiver) = create_data_client_with_receiver_and_config_for_test(config);
2932
2933        assert!(client.tasks.is_empty());
2934        client
2935            .spawn_instrument_refresh()
2936            .expect("instrument refresh task registration");
2937        assert_eq!(client.tasks.len(), 1);
2938
2939        client.tasks.begin_shutdown();
2940        client.shutdown_tasks().await.expect("task shutdown");
2941    }
2942
2943    #[tokio::test]
2944    async fn test_await_instrument_refresh_drops_result_when_request_cancels() {
2945        let cancellation = CancellationToken::new();
2946        let request_cancellation = cancellation.clone();
2947
2948        let result = await_instrument_refresh(&cancellation, async move {
2949            request_cancellation.cancel();
2950            42
2951        })
2952        .await;
2953
2954        assert_eq!(result, None);
2955    }
2956
2957    #[tokio::test]
2958    async fn test_reset_closes_registered_task_generation_until_drain() {
2959        let (mut client, _receiver) = create_data_client_with_receiver_for_test();
2960        let old_token = client.cancellation_token.clone();
2961        let (started_tx, started_rx) = tokio::sync::oneshot::channel();
2962        let (dropped_tx, dropped_rx) = tokio::sync::oneshot::channel();
2963
2964        client
2965            .tasks
2966            .spawn(async move {
2967                let _drop_signal = DropSignal(Some(dropped_tx));
2968                let _ = started_tx.send(());
2969                std::future::pending::<()>().await;
2970            })
2971            .expect("registered task spawn");
2972        started_rx.await.expect("registered task started");
2973
2974        client.reset().expect("reset");
2975
2976        assert!(old_token.is_cancelled());
2977        assert_eq!(client.tasks.len(), 1);
2978        assert!(!client.tasks.is_open());
2979        assert!(client.cancellation_token.is_cancelled());
2980        client.shutdown_tasks().await.expect("reset task shutdown");
2981        assert!(client.tasks.is_empty());
2982        tokio::time::timeout(Duration::from_secs(2), dropped_rx)
2983            .await
2984            .expect("registered task was not aborted")
2985            .expect("drop signal sender dropped");
2986    }
2987
2988    #[tokio::test]
2989    async fn test_spawn_task_suppresses_output_after_cancellation() {
2990        let (client, mut receiver) = create_data_client_with_receiver_for_test();
2991        let instrument_id = cache_test_instrument(&client, 0, "ETH", LighterProductType::Perp);
2992        let instrument = client
2993            .instruments
2994            .get_cloned(&instrument_id)
2995            .expect("cached instrument");
2996
2997        // Cancel before the spawn so the biased select drops the future before it can send
2998        client.cancellation_token.cancel();
2999
3000        let sender = client.data_sender.clone();
3001        client.spawn_task(async move {
3002            let _ = sender.send(DataEvent::Data(instrument.into()));
3003        });
3004
3005        let result = tokio::time::timeout(Duration::from_millis(200), receiver.recv()).await;
3006        assert!(
3007            result.is_err(),
3008            "expected no DataEvent after cancellation, was {result:?}",
3009        );
3010    }
3011
3012    #[tokio::test]
3013    async fn test_connect_is_idempotent_when_already_connected() {
3014        let (mut client, _receiver) = create_data_client_with_receiver_for_test();
3015        client.is_connected.store(true, Ordering::Release);
3016
3017        client
3018            .connect()
3019            .await
3020            .expect("connect returns Ok when already connected");
3021
3022        assert!(
3023            client.tasks.is_empty(),
3024            "an already-connected client must not spawn duplicate tasks",
3025        );
3026        assert!(client.is_connected());
3027    }
3028
3029    #[tokio::test]
3030    async fn test_disconnect_drains_in_flight_task_and_suppresses_late_event() {
3031        let (mut client, mut receiver) = create_data_client_with_receiver_for_test();
3032        let instrument_id = cache_test_instrument(&client, 0, "ETH", LighterProductType::Perp);
3033        let instrument = client
3034            .instruments
3035            .get_cloned(&instrument_id)
3036            .expect("cached instrument");
3037        client.is_connected.store(true, Ordering::Release);
3038
3039        // In-flight task (never-released barrier) that would emit; disconnect must drop it first
3040        let sender = client.data_sender.clone();
3041        let (hold_tx, hold_rx) = tokio::sync::oneshot::channel::<()>();
3042        client.spawn_task(async move {
3043            let _ = hold_rx.await;
3044            let _ = sender.send(DataEvent::Data(instrument.into()));
3045        });
3046        assert_eq!(client.tasks.len(), 1);
3047
3048        client.disconnect().await.expect("disconnect");
3049
3050        assert!(
3051            client.tasks.is_empty(),
3052            "disconnect must drain tracked tasks",
3053        );
3054        assert!(!client.is_connected());
3055        let result = tokio::time::timeout(Duration::from_millis(200), receiver.recv()).await;
3056        assert!(
3057            result.is_err(),
3058            "expected no DataEvent after disconnect, was {result:?}",
3059        );
3060
3061        drop(hold_tx);
3062    }
3063
3064    #[tokio::test]
3065    async fn test_disconnect_aborts_task_that_ignores_cancellation() {
3066        let (mut client, _receiver) = create_data_client_with_receiver_for_test();
3067        client.is_connected.store(true, Ordering::Release);
3068
3069        let (started_tx, started_rx) = tokio::sync::oneshot::channel();
3070        let (dropped_tx, dropped_rx) = tokio::sync::oneshot::channel();
3071
3072        // The task ignores cancellation, so shutdown_tasks must abort it after the grace timeout.
3073        client
3074            .tasks
3075            .spawn(async move {
3076                let _drop_signal = DropSignal(Some(dropped_tx));
3077                let _ = started_tx.send(());
3078                std::future::pending::<()>().await;
3079            })
3080            .expect("uncancellable task spawn");
3081        started_rx.await.expect("task started");
3082
3083        client.disconnect().await.expect("disconnect");
3084
3085        assert!(client.tasks.is_empty());
3086        assert!(!client.is_connected());
3087        tokio::time::timeout(Duration::from_secs(5), dropped_rx)
3088            .await
3089            .expect("task aborted after timeout")
3090            .expect("drop signal sender dropped");
3091    }
3092
3093    #[rstest]
3094    fn test_rollback_market_stats_subscription_clears_piggybacked_flags() {
3095        let subscriptions = DashMap::new();
3096        let generations = DashMap::new();
3097        let instrument_id = InstrumentId::new(Symbol::new("ETH-PERP"), *LIGHTER_VENUE);
3098        subscriptions.insert(
3099            instrument_id,
3100            MarketStatsSubscription {
3101                channel: LighterWsChannel::MarketStats(LighterMarketSelection::Market(0)),
3102                flags: MarketStatsFlags {
3103                    mark_price: true,
3104                    index_price: true,
3105                    ..Default::default()
3106                },
3107            },
3108        );
3109        generations.insert(instrument_id, 7);
3110
3111        rollback_market_stats_subscription(&subscriptions, &generations, instrument_id, 7);
3112
3113        assert!(
3114            !subscriptions.contains_key(&instrument_id),
3115            "all flags share the failed underlying channel",
3116        );
3117        assert!(!generations.contains_key(&instrument_id));
3118    }
3119
3120    #[rstest]
3121    fn test_rollback_market_stats_subscription_keeps_replacement_generation() {
3122        let subscriptions = DashMap::new();
3123        let generations = DashMap::new();
3124        let instrument_id = InstrumentId::new(Symbol::new("ETH-PERP"), *LIGHTER_VENUE);
3125        let replacement = MarketStatsSubscription {
3126            channel: LighterWsChannel::MarketStats(LighterMarketSelection::Market(0)),
3127            flags: MarketStatsFlags {
3128                funding_rate: true,
3129                ..Default::default()
3130            },
3131        };
3132        subscriptions.insert(instrument_id, replacement.clone());
3133        generations.insert(instrument_id, 8);
3134
3135        rollback_market_stats_subscription(&subscriptions, &generations, instrument_id, 7);
3136
3137        assert_eq!(
3138            subscriptions
3139                .get(&instrument_id)
3140                .expect("replacement retained")
3141                .flags,
3142            replacement.flags,
3143        );
3144        assert_eq!(generations.get(&instrument_id).map(|value| *value), Some(8));
3145    }
3146
3147    #[rstest]
3148    fn data_constructor_rejects_proxy_without_scheme() {
3149        let (sender, _receiver) = tokio::sync::mpsc::unbounded_channel();
3150        replace_data_event_sender(sender);
3151
3152        let config = LighterDataClientConfig {
3153            proxy_url: Some("127.0.0.1:8080".into()),
3154            ..Default::default()
3155        };
3156
3157        assert_eq!(
3158            LighterDataClient::new(ClientId::from("LIGHTER"), config)
3159                .unwrap_err()
3160                .to_string(),
3161            "Lighter proxy_url must be an absolute http:// or https:// URL with a host"
3162        );
3163    }
3164
3165    fn create_data_client_for_test() -> LighterDataClient {
3166        create_data_client_with_receiver_for_test().0
3167    }
3168
3169    fn create_data_client_with_receiver_for_test() -> (
3170        LighterDataClient,
3171        tokio::sync::mpsc::UnboundedReceiver<DataEvent>,
3172    ) {
3173        create_data_client_with_receiver_and_config_for_test(LighterDataClientConfig::default())
3174    }
3175
3176    fn create_data_client_with_receiver_and_config_for_test(
3177        mut config: LighterDataClientConfig,
3178    ) -> (
3179        LighterDataClient,
3180        tokio::sync::mpsc::UnboundedReceiver<DataEvent>,
3181    ) {
3182        config.api_key_index = Some(5);
3183        config.account_index = Some(12_345);
3184        config.private_key = Some(PRIVATE_KEY_HEX.into());
3185        let (sender, receiver) = tokio::sync::mpsc::unbounded_channel();
3186        replace_data_event_sender(sender);
3187        let client = LighterDataClient::new(ClientId::new("LIGHTER"), config).unwrap();
3188        (client, receiver)
3189    }
3190
3191    async fn spawn_order_book_details_server() -> String {
3192        let app = Router::new().route("/api/v1/orderBookDetails", get(order_book_details));
3193        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
3194        let addr = listener.local_addr().unwrap();
3195        tokio::spawn(async move {
3196            axum::serve(listener, app).await.unwrap();
3197        });
3198
3199        format!("http://{addr}")
3200    }
3201
3202    async fn spawn_fundings_server() -> String {
3203        let app = Router::new().route("/api/v1/fundings", get(fundings));
3204        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
3205        let addr = listener.local_addr().unwrap();
3206        tokio::spawn(async move {
3207            axum::serve(listener, app).await.unwrap();
3208        });
3209
3210        format!("http://{addr}")
3211    }
3212
3213    async fn spawn_trades_server() -> String {
3214        spawn_trades_server_with_response(HTTP_RECENT_TRADES).await
3215    }
3216
3217    async fn spawn_trades_server_with_response(response_body: &'static str) -> String {
3218        spawn_trades_server_with_response_and_limit(response_body, 50).await
3219    }
3220
3221    async fn spawn_trades_server_with_response_and_limit(
3222        response_body: &'static str,
3223        expected_limit: u16,
3224    ) -> String {
3225        let app = Router::new().route(
3226            "/api/v1/recentTrades",
3227            get(
3228                move |Query(query): Query<LighterRecentTradesQuery>| async move {
3229                    recent_trades_response(&query, response_body, expected_limit)
3230                },
3231            ),
3232        );
3233        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
3234        let addr = listener.local_addr().unwrap();
3235        tokio::spawn(async move {
3236            axum::serve(listener, app).await.unwrap();
3237        });
3238
3239        format!("http://{addr}")
3240    }
3241
3242    async fn order_book_details() -> Response {
3243        (StatusCode::OK, HTTP_ORDER_BOOK_DETAILS).into_response()
3244    }
3245
3246    async fn fundings(Query(query): Query<LighterFundingsQuery>) -> Response {
3247        assert_eq!(query.market_id, 0);
3248        assert_eq!(query.resolution, LighterFundingResolution::OneHour);
3249        assert_eq!(query.start_timestamp, 1_778_702_400_000);
3250        assert_eq!(query.end_timestamp, 1_778_706_000_000);
3251        assert_eq!(
3252            query.count_back,
3253            i64::from(crate::http::client::LIGHTER_FUNDINGS_MAX_LIMIT)
3254        );
3255        (StatusCode::OK, HTTP_FUNDINGS).into_response()
3256    }
3257
3258    fn recent_trades_response(
3259        query: &LighterRecentTradesQuery,
3260        response_body: &'static str,
3261        expected_limit: u16,
3262    ) -> Response {
3263        assert_eq!(query.market_id, 0);
3264        assert_eq!(query.limit, expected_limit);
3265        (StatusCode::OK, response_body).into_response()
3266    }
3267
3268    fn cache_test_instrument(
3269        client: &LighterDataClient,
3270        market_index: i64,
3271        venue_symbol: &str,
3272        product_type: LighterProductType,
3273    ) -> InstrumentId {
3274        let instrument_id = client
3275            .registry
3276            .insert(market_index, venue_symbol, product_type);
3277        let instrument = match product_type {
3278            LighterProductType::Perp => test_perp_instrument(instrument_id, venue_symbol),
3279            LighterProductType::Spot => test_spot_instrument(instrument_id, venue_symbol),
3280            other => panic!("unsupported product type {other}"),
3281        };
3282
3283        client.instruments.rcu(|m| {
3284            m.insert(instrument_id, instrument.clone());
3285        });
3286
3287        instrument_id
3288    }
3289
3290    fn test_perp_instrument(instrument_id: InstrumentId, venue_symbol: &str) -> InstrumentAny {
3291        InstrumentAny::CryptoPerpetual(
3292            CryptoPerpetual::builder()
3293                .instrument_id(instrument_id)
3294                .raw_symbol(Symbol::new(format!("{venue_symbol}-PERP")))
3295                .base_currency(Currency::from(venue_symbol))
3296                .quote_currency(Currency::from("USDC"))
3297                .settlement_currency(Currency::from("USDC"))
3298                .is_inverse(false)
3299                .price_precision(2)
3300                .size_precision(4)
3301                .price_increment(Price::from("0.01"))
3302                .size_increment(Quantity::from("0.0001"))
3303                .ts_event(UnixNanos::default())
3304                .ts_init(UnixNanos::default())
3305                .build()
3306                .unwrap(),
3307        )
3308    }
3309
3310    fn test_spot_instrument(instrument_id: InstrumentId, venue_symbol: &str) -> InstrumentAny {
3311        InstrumentAny::CurrencyPair(
3312            CurrencyPair::builder()
3313                .instrument_id(instrument_id)
3314                .raw_symbol(Symbol::new(format!("{venue_symbol}-SPOT")))
3315                .base_currency(Currency::from(venue_symbol))
3316                .quote_currency(Currency::from("USDC"))
3317                .price_precision(2)
3318                .size_precision(4)
3319                .price_increment(Price::from("0.01"))
3320                .size_increment(Quantity::from("0.0001"))
3321                .ts_event(UnixNanos::default())
3322                .ts_init(UnixNanos::default())
3323                .build()
3324                .unwrap(),
3325        )
3326    }
3327
3328    fn unsupported_three_minute_bar_type() -> BarType {
3329        let instrument_id = InstrumentId::new(Symbol::new("ETH-PERP"), *LIGHTER_VENUE);
3330        BarType::new(
3331            instrument_id,
3332            BarSpecification::new(3, BarAggregation::Minute, PriceType::Last),
3333            AggregationSource::External,
3334        )
3335    }
3336}