Skip to main content

nautilus_kalshi/
data.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Live Kalshi data client.
17
18pub(crate) mod parse;
19
20mod history;
21mod lifecycle;
22
23use std::{
24    cell::RefCell,
25    collections::HashMap,
26    future::Future,
27    rc::Rc,
28    sync::{
29        Arc, Mutex,
30        atomic::{AtomicBool, Ordering},
31    },
32    time::Duration,
33};
34
35use anyhow::Context;
36use async_trait::async_trait;
37use nautilus_common::{
38    cache::{Cache, CacheView},
39    clients::{DataClient, execute_instrument_subscriptions},
40    live::{dst::time, sender::EventSender},
41    messages::{DataEvent, data::*},
42};
43use nautilus_core::{
44    Params, UUID4,
45    time::{AtomicTime, get_atomic_clock_realtime},
46};
47use nautilus_live::task::{TaskGroup, TaskGroupGuard, TaskSpawner};
48use nautilus_model::{
49    data::Data,
50    enums::BookType,
51    identifiers::{ClientId, InstrumentId, Venue},
52    instruments::{BinaryOption, Instrument, InstrumentAny},
53    orderbook::OrderBook,
54};
55use tokio_util::sync::CancellationToken;
56
57use self::lifecycle::LifecycleTracker;
58pub use self::parse::{quote, trade};
59use crate::{
60    book::{BookSyncTracker, Levels},
61    common::{consts::KALSHI_VENUE, parse::parse_ticker},
62    config::KalshiDataClientConfig,
63    http::client::KalshiHttpClient,
64    providers::{KalshiInstrumentProvider, request_bounds},
65    websocket::{
66        client::{KalshiWebSocketClient, KalshiWsEvent},
67        messages::{KalshiChannel, KalshiDataMessage, KalshiSubscription, KalshiWsMessage},
68    },
69};
70
71const TASK_GRACE: Duration = Duration::from_secs(5);
72const TASK_FORCE: Duration = Duration::from_secs(2);
73
74/// Streams selected binary markets as exact YES-priced L2 books, quotes, trades, status, and closes.
75///
76/// Connection publishes fresh definitions for every selected market before streaming. Subscriptions
77/// are reference counted independently for books, quotes, and trades, and survive stop or disconnect.
78/// Book, quote, and trade channels each share one wire subscription across the selected markets.
79/// Per-market demand controls delivery; the wire subscription ends when its last reference is released.
80/// Reset clears demand; disposal permanently closes admission. Ticker quotes require both prices
81/// and positive sizes in the same message. Incomplete and empty sides are not carried forward.
82#[derive(Debug)]
83pub struct KalshiDataClient {
84    clock: &'static AtomicTime,
85    cache: CacheView,
86    client_id: ClientId,
87    config: KalshiDataClientConfig,
88    provider: Arc<KalshiInstrumentProvider>,
89    ws_client: Option<KalshiWebSocketClient>,
90    connected: Arc<AtomicBool>,
91    disposed: bool,
92    session_tasks: TaskGroup,
93    command_tasks: TaskGroup,
94    sender: EventSender<DataEvent>,
95    instruments: Vec<InstrumentId>,
96    context: Arc<Mutex<HashMap<InstrumentId, BinaryOption>>>,
97    demand: Arc<Mutex<HashMap<InstrumentId, Demand>>>,
98    lifecycle: Arc<LifecycleTracker>,
99    books: BookSyncTracker,
100}
101
102#[allow(
103    clippy::missing_panics_doc,
104    reason = "client state mutex poisoning is not expected"
105)]
106impl KalshiDataClient {
107    /// Creates a disconnected client for a nonempty set of distinct native markets.
108    ///
109    /// The sender accepts the engine dispatch sender or a standalone Tokio sender converted with
110    /// `into()`. Only selected markets can stream; explicit instrument requests remain fresh and
111    /// preserve their original filters and correlation IDs.
112    ///
113    /// # Errors
114    ///
115    /// Returns an error if configuration is invalid, markets are empty, repeated, or foreign,
116    /// or HTTP transport setup fails.
117    pub fn new(
118        client_id: ClientId,
119        config: KalshiDataClientConfig,
120        instruments: Vec<InstrumentId>,
121        sender: EventSender<DataEvent>,
122    ) -> anyhow::Result<Self> {
123        config.validate()?;
124        anyhow::ensure!(
125            !instruments.is_empty(),
126            "bootstrap markets must not be empty"
127        );
128        let mut selected = std::collections::HashSet::new();
129
130        for id in &instruments {
131            parse_ticker(*id)?;
132            anyhow::ensure!(selected.insert(*id), "duplicate bootstrap market");
133        }
134
135        let http = KalshiHttpClient::new(&config)?;
136        let clock = get_atomic_clock_realtime();
137        let provider = KalshiInstrumentProvider::new(http, clock, sender.clone());
138
139        let books = BookSyncTracker::new(
140            &instruments,
141            Duration::from_secs(config.book_snapshot_timeout_secs),
142        );
143
144        Ok(Self {
145            clock,
146            cache: Rc::new(RefCell::new(Cache::default())).into(),
147            client_id,
148            config,
149            provider: Arc::new(provider),
150            ws_client: None,
151            connected: Arc::new(AtomicBool::new(false)),
152            disposed: false,
153            session_tasks: TaskGroup::new(),
154            command_tasks: TaskGroup::new(),
155            sender,
156            instruments,
157            context: Arc::default(),
158            demand: Arc::default(),
159            lifecycle: Arc::default(),
160            books,
161        })
162    }
163
164    pub(crate) fn with_runtime(
165        client_id: ClientId,
166        config: KalshiDataClientConfig,
167        sender: EventSender<DataEvent>,
168        cache: CacheView,
169    ) -> anyhow::Result<Self> {
170        let instruments = config.instrument_ids.clone();
171        let mut client = Self::new(client_id, config, instruments, sender)?;
172        client.cache = cache;
173        client.require_cached_binary_options()?;
174        Ok(client)
175    }
176
177    fn require_cached_binary_options(&self) -> anyhow::Result<()> {
178        let cache = self.cache.borrow();
179        for id in &self.instruments {
180            if let Some(instrument) = cache.instrument(id) {
181                anyhow::ensure!(
182                    matches!(instrument, InstrumentAny::BinaryOption(_)) && instrument.id() == *id,
183                    "cached instrument {id} is not a Kalshi binary option"
184                );
185            }
186        }
187
188        Ok(())
189    }
190
191    #[cfg(all(test, not(all(feature = "simulation", madsim))))]
192    pub(crate) fn config(&self) -> &KalshiDataClientConfig {
193        &self.config
194    }
195
196    #[cfg(all(test, not(all(feature = "simulation", madsim))))]
197    pub(crate) fn instruments(&self) -> &[InstrumentId] {
198        &self.instruments
199    }
200
201    #[cfg(all(test, not(all(feature = "simulation", madsim))))]
202    pub(crate) fn cache(&self) -> &CacheView {
203        &self.cache
204    }
205
206    fn subscribe_lifecycle(
207        &self,
208        id: InstrumentId,
209        close: bool,
210        subscribe: bool,
211    ) -> anyhow::Result<()> {
212        anyhow::ensure!(!self.disposed, "Kalshi data client is disposed");
213        anyhow::ensure!(!self.sender.is_closed(), "data event receiver closed");
214        anyhow::ensure!(
215            self.instruments.contains(&id),
216            "instrument is not a selected bootstrap market"
217        );
218        self.lifecycle.subscribe(
219            id,
220            close,
221            subscribe,
222            &self.context,
223            &self.sender,
224            self.clock.get_time_ns(),
225        )
226    }
227
228    fn subscribe_market(&self, id: InstrumentId, quotes: bool) -> anyhow::Result<()> {
229        anyhow::ensure!(!self.disposed, "Kalshi data client is disposed");
230        anyhow::ensure!(
231            self.instruments.contains(&id),
232            "instrument is not a selected bootstrap market"
233        );
234        anyhow::ensure!(!self.sender.is_closed(), "data event receiver closed");
235        let mut demand = self.demand.lock().expect("demand lock is not poisoned");
236        let first = demand.values().all(|entry| entry.count(quotes) == 0);
237        let entry = demand.entry(id).or_default();
238        let count = entry.count_mut(quotes);
239        let next = count
240            .checked_add(1)
241            .context("subscription reference count overflow")?;
242
243        if first && let Some(ws_client) = &self.ws_client {
244            let subscription = subscription(&self.instruments, quotes)?;
245            if let Err(e) = ws_client.subscribe(subscription.clone()) {
246                if let Err(e) = ws_client.unsubscribe(&subscription) {
247                    log::warn!("Kalshi subscription rollback notification failed: {e}");
248                }
249
250                return Err(e);
251            }
252        }
253
254        *count = next;
255        Ok(())
256    }
257
258    fn unsubscribe_market(&self, id: InstrumentId, quotes: bool) -> anyhow::Result<()> {
259        let mut demand = self.demand.lock().expect("demand lock is not poisoned");
260
261        let Some(entry) = demand.get_mut(&id) else {
262            return Ok(());
263        };
264
265        let count = entry.count_mut(quotes);
266        if *count == 0 {
267            return Ok(());
268        }
269
270        *count -= 1;
271        let last = demand.values().all(|entry| entry.count(quotes) == 0);
272        if last && let Some(ws_client) = &self.ws_client {
273            let subscription = subscription(&self.instruments, quotes)?;
274            ws_client.unsubscribe(&subscription)?;
275        }
276
277        Ok(())
278    }
279
280    fn spawn_request<F>(&self, future: F) -> anyhow::Result<()>
281    where
282        F: Future<Output = anyhow::Result<()>> + Send + 'static,
283    {
284        anyhow::ensure!(!self.disposed, "Kalshi data client is disposed");
285        anyhow::ensure!(!self.sender.is_closed(), "data event receiver closed");
286        let cancellation = self.command_tasks.cancellation_token();
287
288        self.command_tasks.spawn(async move {
289            tokio::select! {
290                biased;
291                () = cancellation.cancelled() => {},
292                result = future => if let Err(e) = result { log::warn!("Kalshi data request failed: {e}"); },
293            }
294        })?;
295
296        Ok(())
297    }
298
299    fn begin_session_shutdown(&mut self) {
300        self.connected.store(false, Ordering::Release);
301        self.books.stop(false);
302        self.session_tasks.begin_shutdown();
303        self.ws_client = None;
304    }
305
306    async fn finish_shutdown(&self) -> anyhow::Result<()> {
307        let (session, commands) = tokio::join!(
308            self.session_tasks.finish_shutdown(TASK_GRACE, TASK_FORCE),
309            self.command_tasks.finish_shutdown(TASK_GRACE, TASK_FORCE)
310        );
311        session?;
312        commands?;
313        Ok(())
314    }
315}
316
317macro_rules! unsupported {
318    ($($name:ident($command:ty)),* $(,)?) => { $(
319        fn $name(&mut self, _command: $command) -> anyhow::Result<()> {
320            anyhow::bail!(concat!("Kalshi does not support ", stringify!($name)))
321        }
322    )* };
323}
324
325#[async_trait(?Send)]
326impl DataClient for KalshiDataClient {
327    fn client_id(&self) -> ClientId {
328        self.client_id
329    }
330
331    fn venue(&self) -> Option<Venue> {
332        Some(*KALSHI_VENUE)
333    }
334
335    fn start(&mut self) -> anyhow::Result<()> {
336        anyhow::ensure!(!self.disposed, "Kalshi data client is disposed");
337        Ok(())
338    }
339
340    fn stop(&mut self) -> anyhow::Result<()> {
341        self.begin_session_shutdown();
342        self.command_tasks.begin_shutdown();
343        Ok(())
344    }
345
346    fn reset(&mut self) -> anyhow::Result<()> {
347        self.stop()?;
348        self.books.stop(true);
349        self.lifecycle.clear();
350        self.demand
351            .lock()
352            .expect("demand lock is not poisoned")
353            .clear();
354        self.context
355            .lock()
356            .expect("context lock is not poisoned")
357            .clear();
358        Ok(())
359    }
360
361    fn dispose(&mut self) -> anyhow::Result<()> {
362        self.reset()?;
363        self.disposed = true;
364        Ok(())
365    }
366
367    fn is_connected(&self) -> bool {
368        self.connected.load(Ordering::Acquire)
369            && !self.sender.is_closed()
370            && self
371                .ws_client
372                .as_ref()
373                .is_some_and(KalshiWebSocketClient::is_active)
374    }
375
376    fn is_disconnected(&self) -> bool {
377        !self.is_connected()
378    }
379
380    async fn connect(&mut self) -> anyhow::Result<()> {
381        anyhow::ensure!(!self.disposed, "Kalshi data client is disposed");
382
383        if self.is_connected() {
384            return Ok(());
385        }
386
387        self.begin_session_shutdown();
388        self.session_tasks
389            .finish_shutdown(TASK_GRACE, TASK_FORCE)
390            .await?;
391        self.session_tasks.start_generation()?;
392
393        if !self.command_tasks.is_open() {
394            self.command_tasks
395                .finish_shutdown(TASK_GRACE, TASK_FORCE)
396                .await?;
397            self.command_tasks.start_generation()?;
398        }
399
400        let connected = Arc::clone(&self.connected);
401        let guard = TaskGroupGuard::new(&[&self.session_tasks], move || {
402            connected.store(false, Ordering::Release);
403        });
404
405        self.lifecycle.begin_recovery();
406        self.context
407            .lock()
408            .expect("context lock is not poisoned")
409            .clear();
410        refresh(
411            &self.provider,
412            &self.instruments,
413            &self.context,
414            &self.lifecycle,
415            &self.sender,
416            &self.session_tasks.cancellation_token(),
417        )
418        .await?;
419        let (ws_client, receiver) = KalshiWebSocketClient::new(self.config.clone())?;
420        ws_client.subscribe(KalshiSubscription {
421            channel: KalshiChannel::MarketLifecycleV2,
422            market_tickers: Vec::new(),
423        })?;
424
425        self.books.replay(&ws_client)?;
426        {
427            let demand = self.demand.lock().expect("demand lock is not poisoned");
428            for quotes in [true, false] {
429                if demand.values().any(|entry| entry.count(quotes) > 0) {
430                    ws_client.subscribe(subscription(&self.instruments, quotes)?)?;
431                }
432            }
433        }
434
435        let session = Session {
436            provider: Arc::clone(&self.provider),
437            instruments: self.instruments.clone(),
438            context: Arc::clone(&self.context),
439            demand: Arc::clone(&self.demand),
440            lifecycle: Arc::clone(&self.lifecycle),
441            books: self.books.clone(),
442            tasks: self.session_tasks.spawner()?,
443            sender: self.sender.clone(),
444            connected: Arc::clone(&self.connected),
445            ws_client: ws_client.clone(),
446            clock: self.clock,
447            refresh_interval: Duration::from_secs(
448                self.config.update_instruments_interval_mins * 60,
449            ),
450        };
451
452        let (startup, initialized) = tokio::sync::oneshot::channel();
453
454        self.session_tasks.spawn(session.run(
455            receiver,
456            self.session_tasks.cancellation_token(),
457            startup,
458        ))?;
459        self.ws_client = Some(ws_client.clone());
460        let result = async {
461            ws_client.connect().await?;
462            time::timeout(
463                Duration::from_secs(self.config.ws_timeout_secs),
464                initialized,
465            )
466            .await
467            .context("initial lifecycle recovery timed out")?
468            .context("initial lifecycle recovery stopped")??;
469            anyhow::ensure!(
470                !self.sender.is_closed(),
471                "data event receiver closed during connect"
472            );
473            Ok(())
474        }
475        .await;
476
477        if let Err(e) = result {
478            drop(guard);
479            self.begin_session_shutdown();
480            self.session_tasks
481                .finish_shutdown(TASK_GRACE, TASK_FORCE)
482                .await
483                .context("failed Kalshi startup cleanup")?;
484            return Err(e);
485        }
486
487        self.connected.store(true, Ordering::Release);
488        guard.disarm();
489        log::info!("Connected {}", self.client_id);
490        Ok(())
491    }
492
493    async fn disconnect(&mut self) -> anyhow::Result<()> {
494        self.stop()?;
495        self.finish_shutdown().await?;
496        log::info!("Disconnected {}", self.client_id);
497        Ok(())
498    }
499
500    fn subscribe_quotes(&mut self, command: SubscribeQuotes) -> anyhow::Result<()> {
501        execute_instrument_subscriptions(&command.instrument_ids, |id| {
502            self.subscribe_market(id, true)
503        })
504    }
505
506    fn subscribe_trades(&mut self, command: SubscribeTrades) -> anyhow::Result<()> {
507        execute_instrument_subscriptions(&command.instrument_ids, |id| {
508            self.subscribe_market(id, false)
509        })
510    }
511
512    fn unsubscribe_quotes(&mut self, command: &UnsubscribeQuotes) -> anyhow::Result<()> {
513        execute_instrument_subscriptions(&command.instrument_ids, |id| {
514            self.unsubscribe_market(id, true)
515        })
516    }
517
518    fn unsubscribe_trades(&mut self, command: &UnsubscribeTrades) -> anyhow::Result<()> {
519        execute_instrument_subscriptions(&command.instrument_ids, |id| {
520            self.unsubscribe_market(id, false)
521        })
522    }
523
524    fn subscribe_book_deltas(&mut self, command: SubscribeBookDeltas) -> anyhow::Result<()> {
525        anyhow::ensure!(!self.disposed, "Kalshi data client is disposed");
526        anyhow::ensure!(!self.sender.is_closed(), "data event receiver closed");
527        anyhow::ensure!(
528            command.book_type == BookType::L2_MBP && command.depth.is_none(),
529            "Kalshi streams full L2 market-by-price books only"
530        );
531        anyhow::ensure!(
532            command
533                .params
534                .as_ref()
535                .is_none_or(|params| params.is_empty()),
536            "Kalshi book subscription parameters are unsupported"
537        );
538        execute_instrument_subscriptions(&command.instrument_ids, |id| {
539            anyhow::ensure!(
540                self.instruments.contains(&id),
541                "instrument is not a selected bootstrap market"
542            );
543            self.books.subscribe(id, self.ws_client.as_ref())
544        })
545    }
546
547    fn unsubscribe_book_deltas(&mut self, command: &UnsubscribeBookDeltas) -> anyhow::Result<()> {
548        execute_instrument_subscriptions(&command.instrument_ids, |id| {
549            self.books.unsubscribe(id, self.ws_client.as_ref())
550        })
551    }
552
553    fn request_book_snapshot(&self, request: RequestBookSnapshot) -> anyhow::Result<()> {
554        let instrument_id = request.single_instrument_id()?;
555        let ticker = parse_ticker(instrument_id)?;
556        let depth = request.depth.map_or(0, |depth| depth.get());
557        anyhow::ensure!(depth <= 100, "Kalshi REST book depth exceeds 100");
558        anyhow::ensure!(
559            request
560                .params
561                .as_ref()
562                .is_none_or(|params| params.is_empty()),
563            "Kalshi book request parameters are unsupported"
564        );
565        let provider = Arc::clone(&self.provider);
566        let sender = self.sender.clone();
567        let client_id = self.client_id;
568        self.spawn_request(async move {
569            let instrument_request = RequestInstrument::new(
570                instrument_id,
571                None,
572                None,
573                None,
574                UUID4::new(),
575                request.ts_init,
576                None,
577            );
578
579            let instrument = provider.load_instrument(&instrument_request).await?;
580            let response = provider.http.get_orderbook(&ticker, depth as u32).await?;
581            let now = provider.clock.get_time_ns();
582            let deltas = Levels::rest(&response.orderbook_fp, &instrument, now)?;
583            let mut book = OrderBook::new(instrument.id, BookType::L2_MBP);
584            book.apply_deltas(&deltas)?;
585
586            let response = BookResponse::new(
587                request.request_id,
588                request.client_id.unwrap_or(client_id),
589                instrument_id,
590                book,
591                None,
592                None,
593                now,
594                request.params,
595            );
596
597            sender
598                .send(DataEvent::Response(DataResponse::Book(response)))
599                .map_err(|_| anyhow::anyhow!("book response receiver closed"))?;
600            Ok(())
601        })
602    }
603
604    fn request_trades(&self, request: RequestTrades) -> anyhow::Result<()> {
605        let instrument_id = request.single_instrument_id()?;
606        let ticker = parse_ticker(instrument_id)?;
607        let now = self.clock.get_time_ns();
608
609        let range = history::HistoryRange::new(
610            request.start,
611            request.end,
612            request.limit,
613            request.params.as_ref(),
614            now,
615        )?;
616
617        let (start, end) = request_bounds(request.start, request.end)?;
618        let provider = Arc::clone(&self.provider);
619        let client_id = request.client_id.unwrap_or(self.client_id);
620        let sender = self.sender.clone();
621        self.spawn_request(async move {
622            let metadata =
623                RequestInstrument::new(instrument_id, None, None, None, UUID4::new(), now, None);
624            let instrument = provider.load_instrument(&metadata).await?;
625            let records = provider
626                .http
627                .get_trades_range(range.trades_query(ticker), range.max_pages)
628                .await?;
629            let mut trades = Vec::new();
630
631            for record in records {
632                let tick = history::trade(record, &instrument)?;
633                if range.contains(tick.ts_event) {
634                    trades.push(tick);
635                }
636            }
637
638            range.truncate(&mut trades);
639
640            let response = TradesResponse::new(
641                request.request_id,
642                client_id,
643                instrument_id,
644                trades,
645                start,
646                end,
647                now,
648                request.params,
649            );
650
651            sender
652                .send(DataEvent::Response(DataResponse::Trades(response)))
653                .map_err(|_| anyhow::anyhow!("trade response receiver closed"))?;
654            Ok(())
655        })
656    }
657
658    fn request_bars(&self, request: RequestBars) -> anyhow::Result<()> {
659        let bar_type = request.single_bar_type()?;
660        let id = bar_type.instrument_id();
661        parse_ticker(id)?;
662        let period = history::period(bar_type)?;
663        let now = self.clock.get_time_ns();
664
665        let range = history::HistoryRange::new(
666            request.start,
667            request.end,
668            request.limit,
669            request.params.as_ref(),
670            now,
671        )?;
672
673        let (start, end) = request_bounds(request.start, request.end)?;
674        let provider = Arc::clone(&self.provider);
675        let client_id = request.client_id.unwrap_or(self.client_id);
676        let sender = self.sender.clone();
677        self.spawn_request(async move {
678            let metadata = RequestInstrument::new(id, None, None, None, UUID4::new(), now, None);
679            let instrument = provider.load_instrument(&metadata).await?;
680            let info = instrument
681                .info
682                .as_ref()
683                .context("missing instrument metadata")?;
684            let market = serde_json::from_value(
685                info.get("market")
686                    .context("missing market metadata")?
687                    .clone(),
688            )?;
689            let series = info
690                .get("event")
691                .and_then(|v| v.get("series_ticker"))
692                .and_then(serde_json::Value::as_str)
693                .context("missing series identity")?;
694            let records = provider
695                .http
696                .get_candlesticks_range(&market, series, &range.candles_query(period))
697                .await?;
698            let mut bars = Vec::new();
699
700            for record in records {
701                let ts_event = history::candle_time(record.end_period_ts)?;
702                if !range.contains(ts_event) || ts_event > now {
703                    continue;
704                }
705
706                if let Some(bar) = history::bar(record, bar_type, &instrument)? {
707                    bars.push(bar);
708                }
709            }
710
711            range.truncate(&mut bars);
712
713            let response = BarsResponse::new(
714                request.request_id,
715                client_id,
716                bar_type,
717                bars,
718                start,
719                end,
720                now,
721                request.params,
722            );
723
724            sender
725                .send(DataEvent::Response(DataResponse::Bars(response)))
726                .map_err(|_| anyhow::anyhow!("bar response receiver closed"))?;
727            Ok(())
728        })
729    }
730
731    fn request_quotes(&self, _request: RequestQuotes) -> anyhow::Result<()> {
732        anyhow::bail!("Kalshi does not provide historical quotes")
733    }
734
735    fn request_instrument(&self, mut request: RequestInstrument) -> anyhow::Result<()> {
736        let instrument_id = request.single_instrument_id()?;
737        parse_ticker(instrument_id)?;
738        request.client_id.get_or_insert(self.client_id);
739        let provider = Arc::clone(&self.provider);
740        let selected = self.instruments.contains(&instrument_id);
741        let context = Arc::clone(&self.context);
742        let sender = self.sender.clone();
743        let lifecycle = Arc::clone(&self.lifecycle);
744        let stamp = lifecycle.begin_read();
745        self.spawn_request(async move {
746            let instrument = provider.load_instrument(&request).await?;
747            if selected {
748                lifecycle.apply(instrument.clone(), stamp, &context, &sender)?;
749            }
750
751            let guard = if selected {
752                Some(lifecycle.response_guard(&[&instrument])?)
753            } else {
754                None
755            };
756
757            let result = provider.respond_instrument(request, instrument);
758            drop(guard);
759            result
760        })
761    }
762
763    fn request_instruments(&self, mut request: RequestInstruments) -> anyhow::Result<()> {
764        anyhow::ensure!(
765            request.venue.is_none_or(|v| v == *KALSHI_VENUE),
766            "instrument request venue must be KALSHI"
767        );
768        request.client_id.get_or_insert(self.client_id);
769        let provider = Arc::clone(&self.provider);
770        let selected = self.instruments.clone();
771        let context = Arc::clone(&self.context);
772        let sender = self.sender.clone();
773        let lifecycle = Arc::clone(&self.lifecycle);
774        let stamp = lifecycle.begin_read();
775        self.spawn_request(async move {
776            let mut scoped = request.clone();
777
778            if !selected.is_empty()
779                && scoped.params.as_ref().is_none_or(|params| {
780                    [
781                        "tickers",
782                        "event_ticker",
783                        "series_ticker",
784                        "min_updated_ts",
785                        "max_updated_ts",
786                    ]
787                    .iter()
788                    .all(|key| !params.contains_key(*key))
789                })
790            {
791                let tickers = selected
792                    .iter()
793                    .map(|id| id.symbol.as_str())
794                    .collect::<Vec<_>>()
795                    .join(",");
796                let mut params = scoped.params.as_ref().map_or_default(Params::to_shared_map);
797                let tickers = Arc::new(tickers.into());
798                params.insert("tickers".into(), tickers);
799                let params = Params::from_shared(params);
800                scoped.params = Some(params);
801            }
802
803            let instruments = provider.load_instruments(&scoped).await?;
804            for instrument in &instruments {
805                if let InstrumentAny::BinaryOption(instrument) = instrument
806                    && selected.contains(&instrument.id)
807                {
808                    lifecycle.apply(instrument.clone(), stamp, &context, &sender)?;
809                }
810            }
811
812            let definitions: Vec<_> = instruments
813                .iter()
814                .filter_map(|instrument| match instrument {
815                    InstrumentAny::BinaryOption(instrument)
816                        if selected.contains(&instrument.id) =>
817                    {
818                        Some(instrument)
819                    }
820                    _ => None,
821                })
822                .collect();
823
824            let guard = lifecycle.response_guard(&definitions)?;
825            drop(definitions);
826            let result = provider.respond_instruments(request, instruments);
827            drop(guard);
828            result
829        })
830    }
831
832    fn subscribe_instrument_status(
833        &mut self,
834        command: SubscribeInstrumentStatus,
835    ) -> anyhow::Result<()> {
836        execute_instrument_subscriptions(&command.instrument_ids, |id| {
837            self.subscribe_lifecycle(id, false, true)
838        })
839    }
840
841    fn unsubscribe_instrument_status(
842        &mut self,
843        command: &UnsubscribeInstrumentStatus,
844    ) -> anyhow::Result<()> {
845        execute_instrument_subscriptions(&command.instrument_ids, |id| {
846            self.subscribe_lifecycle(id, false, false)
847        })
848    }
849
850    fn subscribe_instrument_close(
851        &mut self,
852        command: SubscribeInstrumentClose,
853    ) -> anyhow::Result<()> {
854        execute_instrument_subscriptions(&command.instrument_ids, |id| {
855            self.subscribe_lifecycle(id, true, true)
856        })
857    }
858
859    fn unsubscribe_instrument_close(
860        &mut self,
861        command: &UnsubscribeInstrumentClose,
862    ) -> anyhow::Result<()> {
863        execute_instrument_subscriptions(&command.instrument_ids, |id| {
864            self.subscribe_lifecycle(id, true, false)
865        })
866    }
867
868    unsupported! {
869        subscribe(SubscribeCustomData), subscribe_instruments(SubscribeInstruments), subscribe_instrument(SubscribeInstrument),
870        subscribe_book_depth(SubscribeBookDepth),
871        subscribe_mark_prices(SubscribeMarkPrices), subscribe_index_prices(SubscribeIndexPrices), subscribe_funding_rates(SubscribeFundingRates),
872        subscribe_bars(SubscribeBars), subscribe_option_greeks(SubscribeOptionGreeks),
873        unsubscribe(&UnsubscribeCustomData), unsubscribe_instruments(&UnsubscribeInstruments), unsubscribe_instrument(&UnsubscribeInstrument),
874        unsubscribe_book_depth(&UnsubscribeBookDepth),
875        unsubscribe_mark_prices(&UnsubscribeMarkPrices), unsubscribe_index_prices(&UnsubscribeIndexPrices), unsubscribe_funding_rates(&UnsubscribeFundingRates),
876        unsubscribe_bars(&UnsubscribeBars), unsubscribe_option_greeks(&UnsubscribeOptionGreeks),
877    }
878}
879
880#[derive(Debug, Default)]
881struct Demand {
882    quotes: usize,
883    trades: usize,
884}
885
886impl Demand {
887    fn count_mut(&mut self, quotes: bool) -> &mut usize {
888        if quotes {
889            &mut self.quotes
890        } else {
891            &mut self.trades
892        }
893    }
894
895    fn count(&self, quotes: bool) -> usize {
896        if quotes { self.quotes } else { self.trades }
897    }
898}
899
900struct Session {
901    provider: Arc<KalshiInstrumentProvider>,
902    instruments: Vec<InstrumentId>,
903    context: Arc<Mutex<HashMap<InstrumentId, BinaryOption>>>,
904    demand: Arc<Mutex<HashMap<InstrumentId, Demand>>>,
905    lifecycle: Arc<LifecycleTracker>,
906    books: BookSyncTracker,
907    tasks: TaskSpawner,
908    sender: EventSender<DataEvent>,
909    connected: Arc<AtomicBool>,
910    ws_client: KalshiWebSocketClient,
911    clock: &'static AtomicTime,
912    refresh_interval: Duration,
913}
914
915impl Session {
916    async fn run(
917        self,
918        mut receiver: tokio::sync::mpsc::UnboundedReceiver<KalshiWsEvent>,
919        cancellation: CancellationToken,
920        startup: tokio::sync::oneshot::Sender<anyhow::Result<()>>,
921    ) {
922        let mut startup = Some(startup);
923        let result = self
924            .receive(&mut receiver, &cancellation, &mut startup)
925            .await;
926
927        if let Some(startup) = startup {
928            let _ = startup.send(Err(anyhow::anyhow!("initial lifecycle recovery failed")));
929        }
930
931        self.connected.store(false, Ordering::Release);
932        self.books.stop(false);
933
934        if let Err(e) = result {
935            log::warn!("Kalshi data stream stopped: {e}");
936        }
937
938        if let Err(e) = self.ws_client.stop().await {
939            log::warn!("Kalshi WebSocket shutdown failed: {e}");
940        }
941    }
942
943    async fn receive(
944        &self,
945        receiver: &mut tokio::sync::mpsc::UnboundedReceiver<KalshiWsEvent>,
946        cancellation: &CancellationToken,
947        startup: &mut Option<tokio::sync::oneshot::Sender<anyhow::Result<()>>>,
948    ) -> anyhow::Result<()> {
949        let mut refresh_tick = time::interval(self.refresh_interval);
950        refresh_tick.tick().await;
951        let mut health_tick = time::interval(Duration::from_millis(100));
952        health_tick.set_missed_tick_behavior(time::MissedTickBehavior::Skip);
953        let mut generation = None;
954        let mut lifecycle_sequence = None;
955        let mut lifecycle_recovered = false;
956
957        loop {
958            let event = tokio::select! {
959                biased;
960                () = cancellation.cancelled() => return Ok(()),
961                _ = health_tick.tick() => { anyhow::ensure!(!self.sender.is_closed(), "data event receiver closed"); self.books.monitor(&self.ws_client, &self.tasks); self.lifecycle.tick(&self.context, &self.sender, self.clock.get_time_ns())?; continue; },
962                _ = refresh_tick.tick() => { self.refresh(&mut refresh_tick, cancellation).await?; continue; },
963                event = receiver.recv() => event.context("WebSocket event receiver closed")?,
964            };
965
966            let current = event.generation();
967
968            if generation.is_some_and(|generation| current < generation) {
969                continue;
970            }
971
972            let new_generation = generation != Some(current);
973            if new_generation {
974                self.lifecycle.begin_recovery();
975                self.refresh(&mut refresh_tick, cancellation).await?;
976                generation = Some(current);
977                lifecycle_sequence = None;
978                lifecycle_recovered = false;
979            }
980
981            if matches!(&event, KalshiWsEvent::Message { message: KalshiWsMessage::Subscribed { msg, .. }, .. } if msg.channel == KalshiChannel::MarketLifecycleV2)
982            {
983                if !new_generation {
984                    self.refresh(&mut refresh_tick, cancellation).await?;
985                }
986
987                lifecycle_recovered = true;
988            }
989
990            if matches!(&event, KalshiWsEvent::Ready { .. }) {
991                if !lifecycle_recovered {
992                    self.refresh(&mut refresh_tick, cancellation).await?;
993                }
994
995                lifecycle_recovered = true;
996
997                if let Some(startup) = startup.take() {
998                    let _ = startup.send(Ok(()));
999                }
1000            }
1001
1002            if !self
1003                .sequence(
1004                    &event,
1005                    &mut lifecycle_sequence,
1006                    &mut refresh_tick,
1007                    cancellation,
1008                )
1009                .await?
1010            {
1011                continue;
1012            }
1013
1014            self.books.event(
1015                &event,
1016                &self.context.lock().expect("context lock is not poisoned"),
1017                &self.sender,
1018                self.clock.get_time_ns(),
1019            )?;
1020
1021            match event {
1022                KalshiWsEvent::Message {
1023                    message: KalshiWsMessage::MarketLifecycleV2(data),
1024                    ..
1025                } => {
1026                    self.receive_lifecycle(&data, &mut refresh_tick, cancellation)
1027                        .await?;
1028                }
1029                KalshiWsEvent::Message { message, .. } => self.dispatch(message)?,
1030                KalshiWsEvent::Error { message, .. } => log::warn!("Kalshi WebSocket: {message}"),
1031                KalshiWsEvent::Ready { .. }
1032                | KalshiWsEvent::BookSequenceGap { .. }
1033                | KalshiWsEvent::BookSnapshotRequested { .. } => {}
1034            }
1035        }
1036    }
1037
1038    async fn receive_lifecycle(
1039        &self,
1040        data: &KalshiDataMessage,
1041        refresh_tick: &mut time::Interval,
1042        cancellation: &CancellationToken,
1043    ) -> anyhow::Result<()> {
1044        if let Some(id) = self
1045            .instruments
1046            .iter()
1047            .find(|id| Some(id.symbol.as_str()) == data.msg["market_ticker"].as_str())
1048        {
1049            self.lifecycle.observe(
1050                *id,
1051                data,
1052                &self.context,
1053                &self.sender,
1054                self.clock.get_time_ns(),
1055            )?;
1056            refresh(
1057                &self.provider,
1058                &[*id],
1059                &self.context,
1060                &self.lifecycle,
1061                &self.sender,
1062                cancellation,
1063            )
1064            .await?;
1065            refresh_tick.reset();
1066
1067            if data.msg["event_type"] == "settled" {
1068                self.recheck_settlement(*id)?;
1069            }
1070        }
1071
1072        Ok(())
1073    }
1074
1075    async fn sequence(
1076        &self,
1077        event: &KalshiWsEvent,
1078        lifecycle_sequence: &mut Option<(u64, u64)>,
1079        refresh_tick: &mut time::Interval,
1080        cancellation: &CancellationToken,
1081    ) -> anyhow::Result<bool> {
1082        if let KalshiWsEvent::Message { message, .. } = event
1083            && let Some((KalshiChannel::MarketLifecycleV2, data)) = message.data()
1084            && let Some(seq) = data.seq
1085        {
1086            if let Some((sid, previous)) = *lifecycle_sequence
1087                && sid == data.sid
1088            {
1089                if seq <= previous {
1090                    return Ok(false);
1091                }
1092
1093                if seq != previous + 1 {
1094                    self.refresh(refresh_tick, cancellation).await?;
1095                }
1096            }
1097
1098            *lifecycle_sequence = Some((data.sid, seq));
1099        }
1100
1101        Ok(true)
1102    }
1103
1104    async fn refresh(
1105        &self,
1106        refresh_tick: &mut time::Interval,
1107        cancellation: &CancellationToken,
1108    ) -> anyhow::Result<()> {
1109        refresh(
1110            &self.provider,
1111            &self.instruments,
1112            &self.context,
1113            &self.lifecycle,
1114            &self.sender,
1115            cancellation,
1116        )
1117        .await?;
1118        refresh_tick.reset();
1119        Ok(())
1120    }
1121
1122    fn recheck_settlement(&self, id: InstrumentId) -> anyhow::Result<()> {
1123        let provider = Arc::clone(&self.provider);
1124        let context = Arc::clone(&self.context);
1125        let lifecycle = Arc::clone(&self.lifecycle);
1126        let sender = self.sender.clone();
1127        let cancellation = self.tasks.cancellation_token();
1128
1129        self.tasks.spawn(async move {
1130            for millis in [250, 500, 1_000, 2_000] {
1131                let finalized = context
1132                    .lock()
1133                    .expect("context lock is not poisoned")
1134                    .get(&id)
1135                    .and_then(|instrument| instrument.info.as_ref())
1136                    .is_some_and(|info| info["market"]["status"] == "finalized");
1137
1138                if finalized {
1139                    return;
1140                }
1141
1142                tokio::select! {
1143                    biased;
1144                    () = cancellation.cancelled() => return,
1145                    () = time::sleep(Duration::from_millis(millis)) => {}
1146                }
1147
1148                if let Err(e) = refresh(
1149                    &provider,
1150                    &[id],
1151                    &context,
1152                    &lifecycle,
1153                    &sender,
1154                    &cancellation,
1155                )
1156                .await
1157                {
1158                    if !cancellation.is_cancelled() {
1159                        log::warn!("Kalshi final settlement recheck failed: {e}");
1160                    }
1161
1162                    return;
1163                }
1164            }
1165        })?;
1166
1167        Ok(())
1168    }
1169
1170    fn dispatch(&self, message: KalshiWsMessage) -> anyhow::Result<()> {
1171        let (data, quotes) = match message {
1172            KalshiWsMessage::Ticker(data) => (data, true),
1173            KalshiWsMessage::Trade(data) => (data, false),
1174            _ => return Ok(()),
1175        };
1176
1177        let Some(ticker) = data
1178            .msg
1179            .get("market_ticker")
1180            .and_then(serde_json::Value::as_str)
1181        else {
1182            log::warn!("Kalshi data frame has no market ticker");
1183            return Ok(());
1184        };
1185
1186        let Some(id) = self
1187            .instruments
1188            .iter()
1189            .find(|id| id.symbol.as_str() == ticker)
1190            .copied()
1191        else {
1192            return Ok(());
1193        };
1194
1195        let demanded = self
1196            .demand
1197            .lock()
1198            .expect("demand lock is not poisoned")
1199            .get(&id)
1200            .is_some_and(|demand| {
1201                if quotes {
1202                    demand.quotes > 0
1203                } else {
1204                    demand.trades > 0
1205                }
1206            });
1207
1208        if !demanded {
1209            return Ok(());
1210        }
1211
1212        let ts_init = self.clock.get_time_ns();
1213
1214        let result = {
1215            let context = self.context.lock().expect("context lock is not poisoned");
1216
1217            let Some(instrument) = context.get(&id) else {
1218                return Ok(());
1219            };
1220
1221            if quotes {
1222                parse::quote(data.msg, instrument, ts_init).map(|tick| tick.map(Data::Quote))
1223            } else {
1224                parse::trade(data.msg, instrument, ts_init).map(|tick| tick.map(Data::Trade))
1225            }
1226        };
1227
1228        match result {
1229            Ok(Some(data)) => self
1230                .sender
1231                .send(DataEvent::Data(data))
1232                .map_err(|_| anyhow::anyhow!("data event receiver closed"))?,
1233            Ok(None) => {}
1234            Err(e) => log::warn!("Invalid Kalshi market data: {e}"),
1235        }
1236
1237        Ok(())
1238    }
1239}
1240
1241fn subscription(ids: &[InstrumentId], quotes: bool) -> anyhow::Result<KalshiSubscription> {
1242    Ok(KalshiSubscription {
1243        channel: if quotes {
1244            KalshiChannel::Ticker
1245        } else {
1246            KalshiChannel::Trade
1247        },
1248        market_tickers: ids
1249            .iter()
1250            .map(|id| parse_ticker(*id))
1251            .collect::<anyhow::Result<_>>()?,
1252    })
1253}
1254
1255async fn refresh(
1256    provider: &KalshiInstrumentProvider,
1257    ids: &[InstrumentId],
1258    context: &Mutex<HashMap<InstrumentId, BinaryOption>>,
1259    lifecycle: &LifecycleTracker,
1260    sender: &EventSender<DataEvent>,
1261    cancellation: &CancellationToken,
1262) -> anyhow::Result<()> {
1263    let stamp = lifecycle.begin_read();
1264
1265    for id in ids {
1266        let request = RequestInstrument::new(
1267            *id,
1268            None,
1269            None,
1270            None,
1271            UUID4::new(),
1272            provider.clock.get_time_ns(),
1273            None,
1274        );
1275
1276        let instrument = tokio::select! {
1277            biased;
1278            () = cancellation.cancelled() => anyhow::bail!("metadata refresh canceled"),
1279            result = provider.load_instrument(&request) => result?,
1280        };
1281        lifecycle.apply(instrument, stamp, context, sender)?;
1282    }
1283
1284    Ok(())
1285}
1286
1287#[cfg(test)]
1288#[cfg(not(all(feature = "simulation", madsim)))]
1289mod tests {
1290    use std::{
1291        process::Command,
1292        sync::{Barrier, atomic::AtomicUsize},
1293    };
1294
1295    use nautilus_common::testing::wait_until_async;
1296    use nautilus_core::UnixNanos;
1297    use nautilus_model::enums::InstrumentCloseType;
1298    use rstest::rstest;
1299    use serde_json::Value;
1300
1301    use super::*;
1302    use crate::{
1303        common::{consts::KALSHI_CLIENT_ID, parse::parse_instrument_id},
1304        http::{
1305            models::{Event, Market},
1306            parse::parse_instrument,
1307        },
1308        websocket::messages::KalshiDataMessage,
1309    };
1310
1311    #[allow(
1312        dead_code,
1313        reason = "shared key fixtures serve both session and integration peers"
1314    )]
1315    mod keys {
1316        include!(concat!(
1317            env!("CARGO_MANIFEST_DIR"),
1318            "/tests/integration/keys.rs"
1319        ));
1320    }
1321    mod http_request {
1322        include!(concat!(
1323            env!("CARGO_MANIFEST_DIR"),
1324            "/tests/common/http_request.rs"
1325        ));
1326    }
1327    #[allow(
1328        dead_code,
1329        reason = "shared peer also serves the complete data-client integration suite"
1330    )]
1331    mod peer {
1332        include!(concat!(
1333            env!("CARGO_MANIFEST_DIR"),
1334            "/tests/common/data_peer.rs"
1335        ));
1336    }
1337
1338    #[rstest]
1339    #[case::late_final(true, false)]
1340    #[case::bounded_non_final(false, false)]
1341    #[case::cancel(false, true)]
1342    #[tokio::test]
1343    async fn settlement_notification_rechecks_rest_until_final_or_bounded_stop(
1344        #[case] finalize: bool,
1345        #[case] cancel: bool,
1346    ) {
1347        tokio::time::timeout(Duration::from_secs(12), async {
1348            let peer = peer::Peer::new().await;
1349            let values: Value =
1350                serde_json::from_str(include_str!("../test_data/instruments.json")).unwrap();
1351            let mut market = values["definitions"]["live"]["market"].clone();
1352            market["status"] = "determined".into();
1353            market["updated_time"] = "2026-10-17T03:30:00Z".into();
1354            *peer.market.lock().unwrap() = Some(market.clone());
1355            let id = parse_instrument_id("KXBTC15M-26OCT162345-45").unwrap();
1356            let (sender, mut events) = tokio::sync::mpsc::unbounded_channel();
1357            let mut client = KalshiDataClient::new(
1358                *KALSHI_CLIENT_ID,
1359                peer.config.clone(),
1360                vec![id],
1361                sender.into(),
1362            )
1363            .unwrap();
1364            client
1365                .subscribe_instrument_close(SubscribeInstrumentClose::new(
1366                    id,
1367                    Some(*KALSHI_CLIENT_ID),
1368                    None,
1369                    UUID4::new(),
1370                    UnixNanos::from(1),
1371                    None,
1372                    None,
1373                ))
1374                .unwrap();
1375
1376            if cancel {
1377                client
1378                    .subscribe_quotes(SubscribeQuotes::new(
1379                        id,
1380                        Some(*KALSHI_CLIENT_ID),
1381                        None,
1382                        UUID4::new(),
1383                        UnixNanos::from(2),
1384                        None,
1385                        None,
1386                    ))
1387                    .unwrap();
1388            }
1389
1390            client.connect().await.unwrap();
1391            let baseline = peer.requests.load(Ordering::SeqCst);
1392
1393            let DataEvent::Data(Data::Instrument(instrument)) = events.recv().await.unwrap() else {
1394                panic!("expected bootstrap definition");
1395            };
1396
1397            assert_eq!(instrument.id(), id);
1398            assert_eq!(client.session_tasks.len(), 1);
1399            peer.response_gate
1400                .forget_permits(tokio::sync::Semaphore::MAX_PERMITS);
1401            peer.response_gate.add_permits(3);
1402            assert!(events.try_recv().is_err());
1403            let frames: Value =
1404                serde_json::from_str(include_str!("../test_data/lifecycle.json")).unwrap();
1405            let mut frame = frames["frames"][2].clone();
1406            frame["type"] = "market_lifecycle_v2".into();
1407            frame["sid"] = 1.into();
1408            frame["seq"] = 1.into();
1409            frame["msg"]["market_ticker"] = id.symbol.as_str().into();
1410            frame["msg"]["event_type"] = "settled".into();
1411            peer.actions.send(("raw".into(), frame)).unwrap();
1412            peer.wait_requests(baseline + 3).await;
1413            wait_until_async(
1414                || async { client.session_tasks.len() == 2 },
1415                Duration::from_secs(10),
1416            )
1417            .await;
1418
1419            if cancel {
1420                peer.emit("ticker", id, false);
1421                assert!(matches!(
1422                    events.recv().await.unwrap(),
1423                    DataEvent::Data(Data::Quote(_))
1424                ));
1425                peer.wait_requests(baseline + 4).await;
1426                client.disconnect().await.unwrap();
1427                assert!(client.session_tasks.all_finished());
1428                assert_eq!(peer.requests.load(Ordering::SeqCst), baseline + 4);
1429            } else if finalize {
1430                market["status"] = "finalized".into();
1431                market["updated_time"] = "2026-10-17T03:45:02.123456Z".into();
1432                market["settlement_value_dollars"] = "0.67".into();
1433                market["settlement_ts"] = "2026-10-17T03:45:01.987654Z".into();
1434                *peer.market.lock().unwrap() = Some(market);
1435                peer.response_gate
1436                    .add_permits(tokio::sync::Semaphore::MAX_PERMITS);
1437
1438                let DataEvent::Data(Data::Instrument(instrument)) = events.recv().await.unwrap()
1439                else {
1440                    panic!("expected final definition");
1441                };
1442
1443                let InstrumentAny::BinaryOption(final_definition) = *instrument else {
1444                    panic!("expected binary option");
1445                };
1446
1447                let DataEvent::Data(Data::InstrumentClose(close)) = events.recv().await.unwrap()
1448                else {
1449                    panic!("expected final close")
1450                };
1451
1452                assert_eq!(
1453                    final_definition.info.as_ref().unwrap()["market"]["status"],
1454                    "finalized"
1455                );
1456                assert_eq!(close.instrument_id, id);
1457                assert_eq!(close.close_price.as_decimal(), "0.67".parse().unwrap());
1458                assert_eq!(close.ts_event.as_u64(), 1_792_208_701_987_654_000);
1459                assert_eq!(close.close_type, InstrumentCloseType::ContractExpired);
1460                wait_until_async(
1461                    || async { client.session_tasks.len() == 1 },
1462                    Duration::from_secs(10),
1463                )
1464                .await;
1465                assert_eq!(peer.requests.load(Ordering::SeqCst), baseline + 6);
1466                assert!(events.try_recv().is_err());
1467                client.disconnect().await.unwrap();
1468            } else {
1469                peer.response_gate
1470                    .add_permits(tokio::sync::Semaphore::MAX_PERMITS);
1471                wait_until_async(
1472                    || async { client.session_tasks.len() == 1 },
1473                    Duration::from_secs(10),
1474                )
1475                .await;
1476                assert_eq!(peer.requests.load(Ordering::SeqCst), baseline + 15);
1477                assert!(events.try_recv().is_err());
1478                client.disconnect().await.unwrap();
1479            }
1480        })
1481        .await
1482        .unwrap();
1483    }
1484
1485    #[tokio::test]
1486    async fn settlement_recheck_canceled_before_first_retry_never_dispatches() {
1487        tokio::time::timeout(Duration::from_secs(2), async {
1488            let peer = peer::Peer::new().await;
1489            let id = parse_instrument_id("KXBTC15M-26OCT162345-45").unwrap();
1490            let (sender, mut output) = tokio::sync::mpsc::unbounded_channel();
1491            let mut client = KalshiDataClient::new(
1492                *KALSHI_CLIENT_ID,
1493                peer.config.clone(),
1494                vec![id],
1495                sender.into(),
1496            )
1497            .unwrap();
1498            let (ws_client, _events) = KalshiWebSocketClient::new(peer.config.clone()).unwrap();
1499
1500            let session = Session {
1501                provider: Arc::clone(&client.provider),
1502                instruments: client.instruments.clone(),
1503                context: Arc::clone(&client.context),
1504                demand: Arc::clone(&client.demand),
1505                lifecycle: Arc::clone(&client.lifecycle),
1506                books: client.books.clone(),
1507                tasks: client.session_tasks.spawner().unwrap(),
1508                sender: client.sender.clone(),
1509                connected: Arc::clone(&client.connected),
1510                ws_client,
1511                clock: client.clock,
1512                refresh_interval: Duration::from_secs(60),
1513            };
1514
1515            let context = Arc::clone(&client.context);
1516
1517            // Hold the retry before its first deadline can start on the shared runtime
1518            {
1519                let _held = context.lock().unwrap();
1520                session.recheck_settlement(id).unwrap();
1521                client.stop().unwrap();
1522            }
1523
1524            client.disconnect().await.unwrap();
1525
1526            assert!(client.session_tasks.all_finished());
1527            assert_eq!(peer.requests.load(Ordering::SeqCst), 0);
1528            assert!(output.try_recv().is_err());
1529        })
1530        .await
1531        .unwrap();
1532    }
1533
1534    #[tokio::test]
1535    async fn slow_periodic_refresh_yields_to_queued_market_data() {
1536        let peer = peer::Peer::new().await;
1537        peer.response_gate
1538            .forget_permits(tokio::sync::Semaphore::MAX_PERMITS);
1539        let fixtures: Value =
1540            serde_json::from_str(include_str!("../test_data/instruments.json")).unwrap();
1541        let market: Market =
1542            serde_json::from_value(fixtures["definitions"]["live"]["market"].clone()).unwrap();
1543        let event: Event =
1544            serde_json::from_value(fixtures["definitions"]["live"]["event"].clone()).unwrap();
1545        let instrument = parse_instrument(&market, &event, UnixNanos::from(1)).unwrap();
1546        let id = instrument.id;
1547        let (sender, mut output) = tokio::sync::mpsc::unbounded_channel();
1548        let sender: EventSender<DataEvent> = sender.into();
1549        let clock = get_atomic_clock_realtime();
1550
1551        let provider = Arc::new(KalshiInstrumentProvider::new(
1552            KalshiHttpClient::new(&peer.config).unwrap(),
1553            clock,
1554            sender.clone(),
1555        ));
1556
1557        let (ws_client, _events) = KalshiWebSocketClient::new(peer.config.clone()).unwrap();
1558
1559        let tasks = TaskGroup::new();
1560
1561        let refresh_interval = Duration::from_millis(1);
1562
1563        let session = Session {
1564            provider,
1565            lifecycle: Arc::default(),
1566            books: BookSyncTracker::new(&[id], Duration::from_secs(10)),
1567            tasks: tasks.spawner().unwrap(),
1568            instruments: vec![id],
1569            context: Arc::new(Mutex::new(HashMap::from([(id, instrument)]))),
1570            demand: Arc::new(Mutex::new(HashMap::from([(
1571                id,
1572                Demand {
1573                    quotes: 0,
1574                    trades: 1,
1575                },
1576            )]))),
1577            sender,
1578            connected: Arc::new(AtomicBool::new(true)),
1579            ws_client,
1580            clock,
1581            refresh_interval,
1582        };
1583
1584        let (input, receiver) = tokio::sync::mpsc::unbounded_channel();
1585        let cancellation = CancellationToken::new();
1586
1587        // Keep the session on the test's local runtime
1588        let session = session.run(
1589            receiver,
1590            cancellation.clone(),
1591            tokio::sync::oneshot::channel().0,
1592        );
1593
1594        let run = tokio::spawn(session); // tokio-import-ok
1595
1596        let result = time::timeout(Duration::from_secs(1), async {
1597            peer.wait_requests(1).await;
1598            tokio::time::pause();
1599            tokio::time::advance(refresh_interval * 2).await;
1600            tokio::time::resume();
1601
1602            let payloads: Value =
1603                serde_json::from_str(include_str!("../test_data/market_data.json")).unwrap();
1604            input
1605                .send(KalshiWsEvent::Message {
1606                    generation: 0,
1607                    message: KalshiWsMessage::Trade(KalshiDataMessage {
1608                        id: None,
1609                        sid: 1,
1610                        seq: Some(1),
1611                        sending_ts_ms: None,
1612                        msg: payloads["trade"].clone(),
1613                    }),
1614                })
1615                .unwrap();
1616
1617            peer.response_gate
1618                .add_permits(tokio::sync::Semaphore::MAX_PERMITS);
1619
1620            loop {
1621                if let DataEvent::Data(Data::Trade(tick)) = output.recv().await.unwrap() {
1622                    return tick;
1623                }
1624            }
1625        })
1626        .await;
1627
1628        cancellation.cancel();
1629        run.await.unwrap();
1630        let tick = result.expect("queued trade must progress after a slow metadata refresh");
1631        assert_eq!(tick.instrument_id, id);
1632        assert_eq!(tick.size.as_decimal(), "7.25".parse().unwrap());
1633        assert_eq!(tick.price.as_decimal(), "0.123456".parse().unwrap());
1634    }
1635
1636    #[rstest]
1637    fn canceled_ready_requests_do_not_poll_their_work() {
1638        let output = Command::new(std::env::current_exe().unwrap())
1639            .args([
1640                "--exact",
1641                "data::tests::canceled_ready_requests_child",
1642                "--test-threads=1",
1643            ])
1644            .env("NAUTILUS_KALSHI_CANCEL_TEST", "1")
1645            .output()
1646            .unwrap();
1647        assert!(
1648            output.status.success(),
1649            "{}",
1650            String::from_utf8_lossy(&output.stdout)
1651        );
1652        assert!(String::from_utf8_lossy(&output.stdout).contains("1 passed; 0 failed;"));
1653    }
1654
1655    #[rstest]
1656    fn canceled_ready_requests_child() {
1657        if std::env::var_os("NAUTILUS_KALSHI_CANCEL_TEST").is_none() {
1658            return;
1659        }
1660
1661        let runtime = tokio::runtime::Builder::new_multi_thread()
1662            .worker_threads(1)
1663            .enable_all()
1664            .build()
1665            .unwrap();
1666        nautilus_common::live::set_runtime(runtime).unwrap();
1667        let (blocked, observed) = std::sync::mpsc::channel();
1668        let gate = Arc::new(Barrier::new(2));
1669        let blocker_gate = Arc::clone(&gate);
1670
1671        let blocker = nautilus_common::live::get_runtime().spawn(async move {
1672            blocked.send(()).unwrap();
1673            blocker_gate.wait();
1674        });
1675
1676        observed.recv_timeout(Duration::from_secs(1)).unwrap();
1677        let (sender, _events) = tokio::sync::mpsc::unbounded_channel();
1678        let id = parse_instrument_id("MARKET-A").unwrap();
1679        let mut client = KalshiDataClient::new(
1680            *KALSHI_CLIENT_ID,
1681            KalshiDataClientConfig::default(),
1682            vec![id],
1683            sender.into(),
1684        )
1685        .unwrap();
1686        let polled = Arc::new(AtomicUsize::new(0));
1687        for _ in 0..64 {
1688            let polled = Arc::clone(&polled);
1689            client
1690                .spawn_request(async move {
1691                    polled.fetch_add(1, Ordering::SeqCst);
1692                    Ok(())
1693                })
1694                .unwrap();
1695        }
1696
1697        client.stop().unwrap();
1698        gate.wait();
1699        nautilus_common::live::get_runtime().block_on(async {
1700            client.disconnect().await.unwrap();
1701            blocker.await.unwrap();
1702        });
1703
1704        assert_eq!(polled.load(Ordering::SeqCst), 0);
1705    }
1706}