1use std::{fmt::Debug, sync::Arc};
19
20use ahash::AHashMap;
21use nautilus_core::{
22 AtomicMap, UnixNanos,
23 string::secret::SecretString,
24 time::{AtomicTime, get_atomic_clock_realtime},
25};
26use nautilus_live::book::snapshot::SnapshotGate;
27use nautilus_model::{
28 data::{Bar, BarType, InstrumentStatus, OrderBookDeltas, QuoteTick, TradeTick},
29 identifiers::{AccountId, InstrumentId, Symbol},
30 instruments::{Instrument, InstrumentAny},
31 reports::OrderStatusReport,
32};
33use nautilus_network::{RECONNECTED, websocket::WebSocketClient};
34use serde::Deserialize;
35use tokio_tungstenite::tungstenite::Message;
36use tokio_util::sync::CancellationToken;
37use ustr::Ustr;
38
39use crate::{
40 common::consts::COINBASE_VENUE,
41 websocket::{
42 client::COINBASE_WS_SUBSCRIPTION_KEYS,
43 error::CoinbaseWsError,
44 messages::{CoinbaseWsMessage, WsEventType, WsOrderUpdate},
45 parse::{
46 parse_ws_candle, parse_ws_l2_snapshot, parse_ws_l2_update, parse_ws_status_product,
47 parse_ws_ticker, parse_ws_trade, parse_ws_user_event_to_order_status_report,
48 },
49 },
50};
51
52fn instrument_id_from_product(product_id: &Ustr) -> InstrumentId {
53 InstrumentId::new(Symbol::new(*product_id), *COINBASE_VENUE)
54}
55
56fn resolve_instrument_id_from_aliases(
57 aliases: &AHashMap<Ustr, Ustr>,
58 product_id: &Ustr,
59) -> InstrumentId {
60 let resolved = aliases.get(product_id).copied().unwrap_or(*product_id);
61 instrument_id_from_product(&resolved)
62}
63
64pub enum HandlerCommand {
66 SetClient(WebSocketClient),
68 Subscribe {
70 channel: crate::common::enums::CoinbaseWsChannel,
71 product_ids: Vec<Ustr>,
72 payload: SecretString,
73 },
74 Unsubscribe {
76 channel: crate::common::enums::CoinbaseWsChannel,
77 product_ids: Vec<Ustr>,
78 payload: SecretString,
79 },
80 BookSubscription {
84 payloads: Vec<SecretString>,
85 cancel: CancellationToken,
86 gate: SnapshotGate,
87 completion: tokio::sync::oneshot::Sender<Result<(), CoinbaseWsError>>,
88 },
89 Disconnect,
91 InitializeInstruments(Vec<InstrumentAny>),
93 UpdateInstrument(Box<InstrumentAny>),
95 AddBarType { key: String, bar_type: BarType },
97 RemoveBarType { key: String },
99 SetAccountId(AccountId),
101}
102
103impl Debug for HandlerCommand {
104 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
105 match self {
106 Self::SetClient(_) => f.write_str("SetClient"),
107 Self::Subscribe { channel, .. } => write!(f, "Subscribe({channel:?})"),
108 Self::Unsubscribe { channel, .. } => write!(f, "Unsubscribe({channel:?})"),
109 Self::BookSubscription { payloads, .. } => {
110 write!(f, "BookSubscription({})", payloads.len())
111 }
112 Self::Disconnect => f.write_str("Disconnect"),
113 Self::InitializeInstruments(v) => write!(f, "InitializeInstruments({})", v.len()),
114 Self::UpdateInstrument(i) => write!(f, "UpdateInstrument({})", i.id()),
115 Self::AddBarType { key, .. } => write!(f, "AddBarType({key})"),
116 Self::RemoveBarType { key } => write!(f, "RemoveBarType({key})"),
117 Self::SetAccountId(id) => write!(f, "SetAccountId({id})"),
118 }
119 }
120}
121
122#[derive(Debug, Clone)]
131pub struct UserOrderUpdate {
132 pub report: Box<OrderStatusReport>,
133 pub update: Box<WsOrderUpdate>,
134 pub instrument: InstrumentAny,
135 pub is_snapshot: bool,
136 pub ts_event: UnixNanos,
137 pub ts_init: UnixNanos,
138}
139
140#[derive(Debug, Clone)]
142pub enum NautilusWsMessage {
143 Trade(TradeTick),
145 Quote(QuoteTick),
147 Deltas(OrderBookDeltas),
149 Bar(Bar),
151 UserOrder(Box<UserOrderUpdate>),
153 FuturesBalanceSummary(Box<crate::websocket::messages::WsFcmBalanceSummary>),
156 InstrumentStatus(Box<InstrumentStatus>),
159 Reconnected,
161 SequenceGap { expected: u64, received: u64 },
165 Error(String),
167}
168
169#[derive(Deserialize)]
170struct SequencedEnvelope {
171 sequence_num: u64,
172}
173
174#[derive(Deserialize)]
175struct VenueError {
176 #[serde(rename = "type")]
177 kind: String,
178 message: String,
179}
180
181#[derive(Debug)]
183pub struct FeedHandler {
184 clock: &'static AtomicTime,
185 signal: Arc<std::sync::atomic::AtomicBool>,
186 client: Option<WebSocketClient>,
187 cmd_rx: tokio::sync::mpsc::UnboundedReceiver<HandlerCommand>,
188 raw_rx: tokio::sync::mpsc::UnboundedReceiver<Message>,
189 instruments: AHashMap<InstrumentId, InstrumentAny>,
190 subscription_aliases: Arc<AtomicMap<Ustr, Ustr>>,
194 bar_types: AHashMap<String, BarType>,
195 account_id: Option<AccountId>,
196 buffer: Vec<NautilusWsMessage>,
197 last_heartbeat_counter: Option<u64>,
198 last_sequence_num: Option<u64>,
199}
200
201impl FeedHandler {
202 pub fn new(
204 signal: Arc<std::sync::atomic::AtomicBool>,
205 cmd_rx: tokio::sync::mpsc::UnboundedReceiver<HandlerCommand>,
206 raw_rx: tokio::sync::mpsc::UnboundedReceiver<Message>,
207 subscription_aliases: Arc<AtomicMap<Ustr, Ustr>>,
208 ) -> Self {
209 Self {
210 clock: get_atomic_clock_realtime(),
211 signal,
212 client: None,
213 cmd_rx,
214 raw_rx,
215 instruments: AHashMap::new(),
216 subscription_aliases,
217 bar_types: AHashMap::new(),
218 account_id: None,
219 buffer: Vec::new(),
220 last_heartbeat_counter: None,
221 last_sequence_num: None,
222 }
223 }
224
225 pub fn set_account_id(&mut self, account_id: AccountId) {
227 self.account_id = Some(account_id);
228 }
229
230 pub async fn next(&mut self) -> Option<NautilusWsMessage> {
234 if self.signal.load(std::sync::atomic::Ordering::Acquire) {
237 self.buffer.clear();
238 return None;
239 }
240
241 if let Some(msg) = self.buffer.pop() {
242 return Some(msg);
243 }
244
245 loop {
246 if self.signal.load(std::sync::atomic::Ordering::Acquire) {
247 return None;
248 }
249
250 tokio::select! {
251 Some(cmd) = self.cmd_rx.recv() => {
252 match cmd {
253 HandlerCommand::SetClient(client) => {
254 self.client = Some(client);
255 }
256 HandlerCommand::Subscribe { payload, .. }
257 | HandlerCommand::Unsubscribe { payload, .. } => {
258 self.send_subscription(&payload).await;
259 }
260 HandlerCommand::BookSubscription { payloads, cancel, gate, completion } => {
261 let result = tokio::select! {
262 biased;
263 () = cancel.cancelled() => continue,
264 result = self.send_book_subscription(&payloads) => result,
265 };
266
267 if result.is_ok() {
268 gate.open();
269 }
270 let _ = completion.send(result);
271 }
272 HandlerCommand::Disconnect => {
273 if let Some(client) = self.client.take() {
274 client.notify_closed();
277 }
278 return None;
279 }
280 HandlerCommand::InitializeInstruments(instruments) => {
281 for inst in instruments {
282 self.instruments.insert(inst.id(), inst);
283 }
284 }
285 HandlerCommand::UpdateInstrument(inst) => {
286 self.instruments.insert(inst.id(), *inst);
287 }
288 HandlerCommand::AddBarType { key, bar_type } => {
289 self.bar_types.insert(key, bar_type);
290 }
291 HandlerCommand::RemoveBarType { key } => {
292 self.bar_types.remove(&key);
293 }
294 HandlerCommand::SetAccountId(account_id) => {
295 self.account_id = Some(account_id);
296 }
297 }
298 }
299 Some(raw) = self.raw_rx.recv() => {
300 match raw {
301 Message::Text(text) => {
302 if let Some(msg) = self.handle_text(&text) {
303 return Some(msg);
304 }
305 }
306 Message::Ping(data) => {
307 if let Some(client) = &self.client
308 && let Err(e) = client.send_pong(data.to_vec()).await
309 {
310 log::warn!("Failed to send pong: {e}");
311 }
312 }
313 Message::Close(_) => return None,
314 _ => {}
315 }
316 }
317 else => return None,
318 }
319 }
320 }
321
322 async fn send_subscription(&self, payload: &SecretString) {
323 let Some(client) = &self.client else {
324 log::warn!("Cannot send subscription, no WebSocket client set");
325 return;
326 };
327
328 if let Err(e) = client
329 .send_text(
330 payload.expose_secret().to_owned(),
331 Some(COINBASE_WS_SUBSCRIPTION_KEYS.as_slice()),
332 )
333 .await
334 {
335 log::error!("Failed to send subscription: {e}");
336 }
337 }
338
339 async fn send_book_subscription(
340 &self,
341 payloads: &[SecretString],
342 ) -> Result<(), CoinbaseWsError> {
343 let client = self
344 .client
345 .as_ref()
346 .ok_or_else(|| CoinbaseWsError::ChannelSend("no WebSocket client set".to_string()))?;
347
348 let epoch = client.connection_epoch();
350
351 for payload in payloads {
352 client
353 .send_text_on_connection(
354 payload.expose_secret().to_owned(),
355 Some(COINBASE_WS_SUBSCRIPTION_KEYS.as_slice()),
356 epoch,
357 )
358 .await
359 .map_err(CoinbaseWsError::TransportSend)?;
360 }
361
362 Ok(())
363 }
364
365 fn handle_text(&mut self, text: &str) -> Option<NautilusWsMessage> {
366 if text == RECONNECTED {
367 self.last_heartbeat_counter = None;
368 self.last_sequence_num = None;
369 return Some(NautilusWsMessage::Reconnected);
370 }
371
372 let ts_init = self.clock.get_time_ns();
373
374 let msg: CoinbaseWsMessage = match serde_json::from_str(text) {
375 Ok(m) => m,
376 Err(e) => {
377 if let Ok(error) = serde_json::from_str::<VenueError>(text)
380 && error.kind == "error"
381 {
382 return Some(NautilusWsMessage::Error(error.message));
383 }
384
385 log::warn!("Failed to parse WS message: {e}");
386
387 let envelope = serde_json::from_str::<SequencedEnvelope>(text).ok()?;
389 return self.note_sequence_num(envelope.sequence_num).map(
390 |(expected, received)| NautilusWsMessage::SequenceGap { expected, received },
391 );
392 }
393 };
394
395 let gap = self.note_sequence_num(msg.sequence_num());
396 let output = self.dispatch_message(msg, ts_init);
397
398 match gap {
399 Some((expected, received)) => {
400 if let Some(output) = output {
402 self.buffer.push(output);
403 }
404 Some(NautilusWsMessage::SequenceGap { expected, received })
405 }
406 None => output,
407 }
408 }
409
410 fn dispatch_message(
411 &mut self,
412 msg: CoinbaseWsMessage,
413 ts_init: UnixNanos,
414 ) -> Option<NautilusWsMessage> {
415 match msg {
416 CoinbaseWsMessage::L2Data {
417 timestamp, events, ..
418 } => self.handle_l2_events(&events, ×tamp, ts_init),
419 CoinbaseWsMessage::MarketTrades { events, .. } => {
420 self.handle_market_trades(&events, ts_init)
421 }
422 CoinbaseWsMessage::Ticker {
423 timestamp, events, ..
424 }
425 | CoinbaseWsMessage::TickerBatch {
426 timestamp, events, ..
427 } => self.handle_ticker(&events, ×tamp, ts_init),
428 CoinbaseWsMessage::Candles { events, .. } => self.handle_candles(&events, ts_init),
429 CoinbaseWsMessage::Heartbeats { events, .. } => {
430 for event in events {
431 if let Some((expected, actual)) =
432 self.note_heartbeat_counter(event.heartbeat_counter)
433 {
434 log::warn!("Heartbeat counter gap: expected {expected}, was {actual}");
435 }
436 }
437 None
438 }
439 CoinbaseWsMessage::Subscriptions { events, .. } => {
440 log::debug!("Subscription state: {events:?}");
444 None
445 }
446 CoinbaseWsMessage::User {
447 timestamp, events, ..
448 } => self.handle_user_events(&events, ×tamp, ts_init),
449 CoinbaseWsMessage::FuturesBalanceSummary { events, .. } => {
450 self.handle_futures_balance_summary(events)
451 }
452 CoinbaseWsMessage::Status {
453 timestamp, events, ..
454 } => self.handle_status_events(&events, ×tamp, ts_init),
455 }
456 }
457
458 fn note_sequence_num(&mut self, sequence_num: u64) -> Option<(u64, u64)> {
459 let gap = self.last_sequence_num.and_then(|last| {
460 let expected = last.saturating_add(1);
461 (sequence_num != expected).then_some((expected, sequence_num))
462 });
463 self.last_sequence_num = Some(sequence_num);
464 gap
465 }
466
467 fn note_heartbeat_counter(&mut self, counter: u64) -> Option<(u64, u64)> {
468 let gap = self.last_heartbeat_counter.and_then(|last| {
469 let expected = last.saturating_add(1);
470 (counter != expected).then_some((expected, counter))
471 });
472 self.last_heartbeat_counter = Some(counter);
473 gap
474 }
475
476 fn handle_l2_events(
477 &mut self,
478 events: &[crate::websocket::messages::WsL2DataEvent],
479 timestamp: &str,
480 ts_init: UnixNanos,
481 ) -> Option<NautilusWsMessage> {
482 let ts_event = match crate::http::parse::parse_rfc3339_timestamp(timestamp) {
483 Ok(ts) => ts,
484 Err(e) => {
485 log::warn!("Failed to parse L2 message timestamp {timestamp}: {e}");
486 ts_init
487 }
488 };
489
490 let mut first: Option<NautilusWsMessage> = None;
491 let aliases = self.subscription_aliases.load();
492
493 for event in events {
494 let instrument_id = resolve_instrument_id_from_aliases(&aliases, &event.product_id);
495
496 let instrument = match self.instruments.get(&instrument_id) {
497 Some(inst) => inst,
498 None => {
499 log::warn!("No instrument cached for {instrument_id}");
500 continue;
501 }
502 };
503
504 let result = match event.event_type {
505 WsEventType::Snapshot => parse_ws_l2_snapshot(event, instrument, ts_event, ts_init),
506 WsEventType::Update => parse_ws_l2_update(event, instrument, ts_event, ts_init),
507 };
508
509 match result {
510 Ok(deltas) => {
511 let msg = NautilusWsMessage::Deltas(deltas);
512
513 if first.is_none() {
514 first = Some(msg);
515 } else {
516 self.buffer.push(msg);
517 }
518 }
519 Err(e) => log::warn!("Failed to parse L2 event: {e}"),
520 }
521 }
522
523 if first.is_some() {
524 self.buffer.reverse();
525 }
526 first
527 }
528
529 fn handle_market_trades(
530 &mut self,
531 events: &[crate::websocket::messages::WsMarketTradesEvent],
532 ts_init: UnixNanos,
533 ) -> Option<NautilusWsMessage> {
534 let aliases = self.subscription_aliases.load();
535
536 for event in events {
537 for trade in &event.trades {
538 let instrument_id = resolve_instrument_id_from_aliases(&aliases, &trade.product_id);
539
540 let instrument = match self.instruments.get(&instrument_id) {
541 Some(inst) => inst,
542 None => {
543 log::warn!("No instrument cached for {instrument_id}");
544 continue;
545 }
546 };
547
548 match parse_ws_trade(trade, instrument, ts_init) {
549 Ok(tick) => {
550 self.buffer_remaining_trades(events, event, trade, ts_init);
551 self.buffer.reverse();
553 return Some(NautilusWsMessage::Trade(tick));
554 }
555 Err(e) => log::warn!("Failed to parse trade: {e}"),
556 }
557 }
558 }
559 None
560 }
561
562 fn buffer_remaining_trades(
563 &mut self,
564 events: &[crate::websocket::messages::WsMarketTradesEvent],
565 current_event: &crate::websocket::messages::WsMarketTradesEvent,
566 current_trade: &crate::websocket::messages::WsTrade,
567 ts_init: UnixNanos,
568 ) {
569 let mut found_current = false;
570 let aliases = self.subscription_aliases.load();
571
572 for event in events {
573 let is_current_event = std::ptr::eq(event, current_event);
574
575 for trade in &event.trades {
576 if !found_current {
577 if is_current_event && std::ptr::eq(trade, current_trade) {
578 found_current = true;
579 }
580 continue;
581 }
582
583 let instrument_id = resolve_instrument_id_from_aliases(&aliases, &trade.product_id);
584
585 if let Some(instrument) = self.instruments.get(&instrument_id)
586 && let Ok(tick) = parse_ws_trade(trade, instrument, ts_init)
587 {
588 self.buffer.push(NautilusWsMessage::Trade(tick));
589 }
590 }
591 }
592 }
593
594 fn handle_ticker(
595 &mut self,
596 events: &[crate::websocket::messages::WsTickerEvent],
597 timestamp: &str,
598 ts_init: UnixNanos,
599 ) -> Option<NautilusWsMessage> {
600 let ts_event = crate::http::parse::parse_rfc3339_timestamp(timestamp).unwrap_or(ts_init);
601
602 let mut first: Option<NautilusWsMessage> = None;
603 let aliases = self.subscription_aliases.load();
604
605 for event in events {
606 for ticker in &event.tickers {
607 let instrument_id =
608 resolve_instrument_id_from_aliases(&aliases, &ticker.product_id);
609
610 let instrument = match self.instruments.get(&instrument_id) {
611 Some(inst) => inst,
612 None => {
613 log::warn!("No instrument cached for {instrument_id}");
614 continue;
615 }
616 };
617
618 match parse_ws_ticker(ticker, instrument, ts_event, ts_init) {
619 Ok(quote) => {
620 let msg = NautilusWsMessage::Quote(quote);
621
622 if first.is_none() {
623 first = Some(msg);
624 } else {
625 self.buffer.push(msg);
626 }
627 }
628 Err(e) => log::warn!("Failed to parse ticker: {e}"),
629 }
630 }
631 }
632
633 if first.is_some() {
634 self.buffer.reverse();
635 }
636 first
637 }
638
639 fn handle_user_events(
640 &mut self,
641 events: &[crate::websocket::messages::WsUserEvent],
642 timestamp: &str,
643 ts_init: UnixNanos,
644 ) -> Option<NautilusWsMessage> {
645 let Some(account_id) = self.account_id else {
646 log::debug!(
647 "Dropping user event: account_id not set (call SetAccountId after connect)"
648 );
649 return None;
650 };
651
652 let ts_event = match crate::http::parse::parse_rfc3339_timestamp(timestamp) {
653 Ok(ts) => ts,
654 Err(e) => {
655 log::warn!("Failed to parse user message timestamp {timestamp}: {e}");
656 ts_init
657 }
658 };
659
660 let mut first: Option<NautilusWsMessage> = None;
661 let aliases = self.subscription_aliases.load();
662
663 for event in events {
664 let is_snapshot = matches!(event.event_type, WsEventType::Snapshot);
665
666 for order in &event.orders {
667 let instrument_id = resolve_instrument_id_from_aliases(&aliases, &order.product_id);
668 let instrument = match self.instruments.get(&instrument_id).cloned() {
669 Some(inst) => inst,
670 None => {
671 log::warn!("No instrument cached for {instrument_id}");
672 continue;
673 }
674 };
675
676 self.emit_user_event_messages(
677 order,
678 &instrument,
679 account_id,
680 is_snapshot,
681 ts_event,
682 ts_init,
683 &mut first,
684 );
685 }
686 }
687
688 if first.is_some() {
689 self.buffer.reverse();
690 }
691 first
692 }
693
694 #[allow(clippy::too_many_arguments)]
695 fn emit_user_event_messages(
696 &mut self,
697 order: &WsOrderUpdate,
698 instrument: &InstrumentAny,
699 account_id: AccountId,
700 is_snapshot: bool,
701 ts_event: UnixNanos,
702 ts_init: UnixNanos,
703 first: &mut Option<NautilusWsMessage>,
704 ) {
705 let report = match parse_ws_user_event_to_order_status_report(
706 order, instrument, account_id, ts_event, ts_init,
707 ) {
708 Ok(r) => r,
709 Err(e) => {
710 log::warn!("Failed to parse user order update: {e}");
711 return;
712 }
713 };
714
715 let msg = NautilusWsMessage::UserOrder(Box::new(UserOrderUpdate {
716 report: Box::new(report),
717 update: Box::new(order.clone()),
718 instrument: instrument.clone(),
719 is_snapshot,
720 ts_event,
721 ts_init,
722 }));
723
724 if first.is_none() {
725 *first = Some(msg);
726 } else {
727 self.buffer.push(msg);
728 }
729 }
730
731 fn handle_status_events(
732 &mut self,
733 events: &[crate::websocket::messages::WsStatusEvent],
734 timestamp: &str,
735 ts_init: UnixNanos,
736 ) -> Option<NautilusWsMessage> {
737 let ts_event = crate::http::parse::parse_rfc3339_timestamp(timestamp).unwrap_or(ts_init);
738
739 let mut first: Option<NautilusWsMessage> = None;
740 let aliases = self.subscription_aliases.load();
741
742 for event in events {
743 for product in &event.products {
744 let canonical = product.id;
745 let resolved = resolve_instrument_id_from_aliases(&aliases, &canonical);
746 let Some(status) = parse_ws_status_product(product, resolved, ts_event, ts_init)
747 else {
748 continue;
749 };
750 let msg = NautilusWsMessage::InstrumentStatus(Box::new(status));
751
752 if first.is_none() {
753 first = Some(msg);
754 } else {
755 self.buffer.push(msg);
756 }
757 }
758 }
759
760 if first.is_some() {
761 self.buffer.reverse();
762 }
763 first
764 }
765
766 fn handle_futures_balance_summary(
767 &mut self,
768 events: Vec<crate::websocket::messages::WsFuturesBalanceSummaryEvent>,
769 ) -> Option<NautilusWsMessage> {
770 let mut first: Option<NautilusWsMessage> = None;
771
772 for event in events {
773 let msg = NautilusWsMessage::FuturesBalanceSummary(Box::new(event.fcm_balance_summary));
774
775 if first.is_none() {
776 first = Some(msg);
777 } else {
778 self.buffer.push(msg);
779 }
780 }
781
782 if first.is_some() {
783 self.buffer.reverse();
784 }
785 first
786 }
787
788 fn handle_candles(
789 &mut self,
790 events: &[crate::websocket::messages::WsCandlesEvent],
791 ts_init: UnixNanos,
792 ) -> Option<NautilusWsMessage> {
793 let mut first: Option<NautilusWsMessage> = None;
794 let aliases = self.subscription_aliases.load();
795
796 for event in events {
797 for candle in &event.candles {
798 let key = candle.product_id.as_str();
799
800 let bar_type = match self.bar_types.get(key) {
801 Some(bt) => *bt,
802 None => {
803 log::debug!("No bar type registered for {key}");
804 continue;
805 }
806 };
807
808 let instrument_id =
809 resolve_instrument_id_from_aliases(&aliases, &candle.product_id);
810
811 let instrument = match self.instruments.get(&instrument_id) {
812 Some(inst) => inst,
813 None => {
814 log::warn!("No instrument cached for {instrument_id}");
815 continue;
816 }
817 };
818
819 match parse_ws_candle(candle, bar_type, instrument, ts_init) {
820 Ok(bar) => {
821 let msg = NautilusWsMessage::Bar(bar);
822
823 if first.is_none() {
824 first = Some(msg);
825 } else {
826 self.buffer.push(msg);
827 }
828 }
829 Err(e) => log::warn!("Failed to parse candle: {e}"),
830 }
831 }
832 }
833
834 if first.is_some() {
835 self.buffer.reverse();
836 }
837 first
838 }
839}
840
841#[cfg(test)]
842mod tests {
843 use std::sync::{Arc, atomic::AtomicBool};
844
845 use nautilus_model::{
846 enums::BookAction,
847 identifiers::Symbol,
848 instruments::CurrencyPair,
849 types::{Currency, Price, Quantity},
850 };
851 use rstest::rstest;
852
853 use super::*;
854 use crate::common::{consts::COINBASE_VENUE, testing::load_test_fixture};
855
856 fn test_handler() -> FeedHandler {
857 let (_cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
858 let (_raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
859 FeedHandler::new(
860 Arc::new(AtomicBool::new(false)),
861 cmd_rx,
862 raw_rx,
863 Arc::new(AtomicMap::new()),
864 )
865 }
866
867 fn btc_usd_instrument() -> InstrumentAny {
868 let instrument_id = InstrumentId::new(Symbol::new("BTC-USD"), *COINBASE_VENUE);
869 InstrumentAny::CurrencyPair(
870 CurrencyPair::builder()
871 .instrument_id(instrument_id)
872 .raw_symbol(Symbol::new("BTC-USD"))
873 .base_currency(Currency::get_or_create_crypto("BTC"))
874 .quote_currency(Currency::get_or_create_crypto("USD"))
875 .price_precision(2)
876 .size_precision(8)
877 .price_increment(Price::from("0.01"))
878 .size_increment(Quantity::from("0.00000001"))
879 .min_quantity(Quantity::from("0.00000001"))
880 .ts_event(UnixNanos::default())
881 .ts_init(UnixNanos::default())
882 .build()
883 .unwrap(),
884 )
885 }
886
887 #[rstest]
888 fn test_handle_text_drops_user_channel_when_account_id_unset() {
889 let json = load_test_fixture("ws_user.json");
890 let mut handler = test_handler();
891
892 assert!(handler.handle_text(&json).is_none());
894 assert!(handler.buffer.is_empty());
895 }
896
897 #[rstest]
898 fn test_handle_user_event_emits_user_order_update() {
899 use nautilus_model::{
900 enums::{OrderSide, OrderStatus},
901 identifiers::AccountId,
902 types::Quantity,
903 };
904
905 use crate::common::enums::CoinbaseProductType;
906
907 let json = load_test_fixture("ws_user.json");
908 let mut handler = test_handler();
909 handler.set_account_id(AccountId::new("COINBASE-001"));
910 handler
911 .instruments
912 .insert(btc_usd_instrument().id(), btc_usd_instrument());
913
914 let msg = handler
915 .handle_text(&json)
916 .expect("handler should emit a user-channel update");
917
918 match msg {
919 NautilusWsMessage::UserOrder(carrier) => {
920 assert_eq!(carrier.report.account_id.as_str(), "COINBASE-001");
922 assert_eq!(carrier.report.instrument_id, btc_usd_instrument().id());
923 assert_eq!(
924 carrier.report.venue_order_id.as_str(),
925 "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
926 );
927 assert_eq!(
928 carrier.report.client_order_id.unwrap().as_str(),
929 "11111-000000-000001"
930 );
931 assert_eq!(carrier.report.order_side, OrderSide::Buy.into());
932 assert_eq!(carrier.report.order_status, OrderStatus::Accepted);
933 assert_eq!(carrier.report.filled_qty, Quantity::from("0.00000000"));
934 assert_eq!(carrier.report.quantity, Quantity::from("0.00100000"));
935
936 assert_eq!(carrier.update.product_id, "BTC-USD");
938 assert_eq!(carrier.update.product_type, CoinbaseProductType::Spot);
939 assert_eq!(carrier.update.cumulative_quantity, "0");
940 assert_eq!(carrier.update.leaves_quantity, "0.001");
941
942 assert_eq!(carrier.instrument.id(), btc_usd_instrument().id());
944 assert!(carrier.ts_event.as_u64() > 0);
945 }
946 other => panic!("expected UserOrder, was {other:?}"),
947 }
948 }
949
950 #[rstest]
951 fn test_handle_text_emits_instrument_status_from_status_channel() {
952 use nautilus_model::enums::MarketStatusAction;
953
954 let json = r#"{
955 "channel": "status",
956 "client_id": "",
957 "timestamp": "2023-02-09T20:29:49.753424311Z",
958 "sequence_num": 0,
959 "events": [
960 {
961 "type": "snapshot",
962 "products": [
963 {
964 "product_type": "SPOT",
965 "id": "BTC-USD",
966 "base_currency": "BTC",
967 "quote_currency": "USD",
968 "base_increment": "0.00000001",
969 "quote_increment": "0.01",
970 "display_name": "BTC/USD",
971 "status": "online",
972 "status_message": "",
973 "min_market_funds": "1"
974 },
975 {
976 "product_type": "SPOT",
977 "id": "ETH-USD",
978 "base_currency": "ETH",
979 "quote_currency": "USD",
980 "base_increment": "0.00000001",
981 "quote_increment": "0.01",
982 "display_name": "ETH/USD",
983 "status": "offline",
984 "status_message": "maintenance",
985 "min_market_funds": "1"
986 }
987 ]
988 }
989 ]
990 }"#;
991 let mut handler = test_handler();
992
993 let first = handler
994 .handle_text(json)
995 .expect("status channel must emit InstrumentStatus");
996 let NautilusWsMessage::InstrumentStatus(status) = first else {
997 panic!("expected InstrumentStatus, was {first:?}");
998 };
999 assert_eq!(status.instrument_id, btc_usd_instrument().id());
1000 assert_eq!(status.action, MarketStatusAction::Trading);
1001 assert_eq!(status.is_trading, Some(true));
1002 assert!(status.reason.is_none());
1003
1004 assert_eq!(handler.buffer.len(), 1);
1006 let NautilusWsMessage::InstrumentStatus(status) = handler.buffer.pop().unwrap() else {
1007 panic!("expected buffered InstrumentStatus");
1008 };
1009 assert_eq!(status.action, MarketStatusAction::Halt);
1010 assert_eq!(status.is_trading, Some(false));
1011 assert_eq!(
1012 status.reason.map(|s| s.to_string()),
1013 Some("maintenance".to_string())
1014 );
1015 }
1016
1017 #[rstest]
1018 fn test_handle_l2_update_uses_batch_timestamp_for_all_deltas() {
1019 let json = load_test_fixture("ws_l2_data_update.json");
1020 let mut handler = test_handler();
1021 handler
1022 .instruments
1023 .insert(btc_usd_instrument().id(), btc_usd_instrument());
1024
1025 let msg = handler
1026 .handle_text(&json)
1027 .expect("handler should emit deltas for a valid L2 update");
1028
1029 let deltas = match msg {
1030 NautilusWsMessage::Deltas(d) => d,
1031 other => panic!("expected Deltas, was {other:?}"),
1032 };
1033
1034 assert!(!deltas.deltas.is_empty());
1035 let expected_ts = deltas.deltas[0].ts_event;
1036 for delta in &deltas.deltas {
1037 assert_eq!(
1038 delta.ts_event, expected_ts,
1039 "all deltas in a batch must share ts_event"
1040 );
1041 }
1042 }
1043
1044 #[rstest]
1045 fn test_handle_l2_update_malformed_timestamp_falls_back_to_ts_init() {
1046 let json = load_test_fixture("ws_l2_data_update.json")
1047 .replace("2026-04-07T14:30:01.456789Z", "not-a-valid-timestamp");
1048 let mut handler = test_handler();
1049 handler
1050 .instruments
1051 .insert(btc_usd_instrument().id(), btc_usd_instrument());
1052
1053 let msg = handler
1054 .handle_text(&json)
1055 .expect("handler should still emit deltas when timestamp is malformed");
1056
1057 let deltas = match msg {
1058 NautilusWsMessage::Deltas(d) => d,
1059 other => panic!("expected Deltas, was {other:?}"),
1060 };
1061
1062 assert!(!deltas.deltas.is_empty());
1063 for delta in &deltas.deltas {
1064 assert_eq!(
1065 delta.ts_event, delta.ts_init,
1066 "malformed timestamp must fall back to ts_init"
1067 );
1068 }
1069 }
1070
1071 #[rstest]
1072 fn test_handle_text_emits_futures_balance_summary_snapshot() {
1073 use rust_decimal::Decimal;
1074
1075 let json = r#"{
1076 "channel": "futures_balance_summary",
1077 "client_id": "",
1078 "timestamp": "2023-02-09T20:33:57.609931463Z",
1079 "sequence_num": 0,
1080 "events": [
1081 {
1082 "type": "snapshot",
1083 "fcm_balance_summary": {
1084 "futures_buying_power": "100.00",
1085 "total_usd_balance": "200.00",
1086 "cbi_usd_balance": "300.00",
1087 "cfm_usd_balance": "400.00",
1088 "total_open_orders_hold_amount": "500.00",
1089 "unrealized_pnl": "600.00",
1090 "daily_realized_pnl": "0",
1091 "initial_margin": "700.00",
1092 "available_margin": "800.00",
1093 "liquidation_threshold": "900.00",
1094 "liquidation_buffer_amount": "1000.00",
1095 "liquidation_buffer_percentage": "1000",
1096 "intraday_margin_window_measure": {
1097 "margin_window_type": "FCM_MARGIN_WINDOW_TYPE_INTRADAY",
1098 "margin_level": "MARGIN_LEVEL_TYPE_BASE",
1099 "initial_margin": "100.00",
1100 "maintenance_margin": "200.00",
1101 "liquidation_buffer_percentage": "1000",
1102 "total_hold": "100.00",
1103 "futures_buying_power": "400.00"
1104 },
1105 "overnight_margin_window_measure": {
1106 "margin_window_type": "FCM_MARGIN_WINDOW_TYPE_OVERNIGHT",
1107 "margin_level": "MARGIN_LEVEL_TYPE_BASE",
1108 "initial_margin": "300.00",
1109 "maintenance_margin": "200.00",
1110 "liquidation_buffer_percentage": "1000",
1111 "total_hold": "-30.00",
1112 "futures_buying_power": "2000.00"
1113 }
1114 }
1115 }
1116 ]
1117 }"#;
1118 let mut handler = test_handler();
1119
1120 let msg = handler
1121 .handle_text(json)
1122 .expect("handler should emit a futures balance summary");
1123 match msg {
1124 NautilusWsMessage::FuturesBalanceSummary(summary) => {
1125 assert_eq!(summary.futures_buying_power, Decimal::from(100));
1126 assert_eq!(summary.total_usd_balance, Decimal::from(200));
1127 assert_eq!(summary.total_open_orders_hold_amount, Decimal::from(500));
1128 assert_eq!(summary.available_margin, Decimal::from(800));
1129 let intraday = &summary.intraday_margin_window_measure;
1130 assert_eq!(intraday.initial_margin, Decimal::from(100));
1131 assert_eq!(intraday.maintenance_margin, Decimal::from(200));
1132 let overnight = &summary.overnight_margin_window_measure;
1133 assert_eq!(overnight.initial_margin, Decimal::from(300));
1134 assert_eq!(overnight.maintenance_margin, Decimal::from(200));
1135 assert_eq!(overnight.total_hold, "-30".parse::<Decimal>().unwrap());
1138 }
1139 other => panic!("expected FuturesBalanceSummary, was {other:?}"),
1140 }
1141 }
1142
1143 #[rstest]
1144 fn test_handle_text_routes_reconnected_sentinel() {
1145 let mut handler = test_handler();
1146 let result = handler.handle_text(RECONNECTED);
1147 assert!(matches!(result, Some(NautilusWsMessage::Reconnected)));
1148 }
1149
1150 #[rstest]
1151 fn test_heartbeat_counter_tracks_sequence_and_detects_gaps() {
1152 let mut handler = test_handler();
1153
1154 assert_eq!(handler.note_heartbeat_counter(42), None);
1155 assert_eq!(handler.last_heartbeat_counter, Some(42));
1156 assert_eq!(handler.note_heartbeat_counter(43), None);
1157 assert_eq!(handler.last_heartbeat_counter, Some(43));
1158 assert_eq!(handler.note_heartbeat_counter(45), Some((44, 45)));
1159 assert_eq!(handler.last_heartbeat_counter, Some(45));
1160 assert_eq!(handler.note_heartbeat_counter(40), Some((46, 40)));
1161 assert_eq!(handler.last_heartbeat_counter, Some(40));
1162 }
1163
1164 #[rstest]
1165 fn test_handle_text_heartbeats_updates_counter_and_reconnect_resets_it() {
1166 let json = load_test_fixture("ws_heartbeats.json");
1167 let mut handler = test_handler();
1168
1169 assert!(handler.handle_text(&json).is_none());
1170 assert_eq!(handler.last_heartbeat_counter, Some(42));
1171
1172 let next = json
1173 .replace("\"heartbeat_counter\": 42", "\"heartbeat_counter\": 43")
1174 .replace("\"sequence_num\": 0", "\"sequence_num\": 1");
1175 assert!(handler.handle_text(&next).is_none());
1176 assert_eq!(handler.last_heartbeat_counter, Some(43));
1177
1178 let result = handler.handle_text(RECONNECTED);
1179 assert!(matches!(result, Some(NautilusWsMessage::Reconnected)));
1180 assert_eq!(handler.last_heartbeat_counter, None);
1181 }
1182
1183 fn eth_usd_instrument() -> InstrumentAny {
1184 let instrument_id = InstrumentId::new(Symbol::new("ETH-USD"), *COINBASE_VENUE);
1185 InstrumentAny::CurrencyPair(
1186 CurrencyPair::builder()
1187 .instrument_id(instrument_id)
1188 .raw_symbol(Symbol::new("ETH-USD"))
1189 .base_currency(Currency::get_or_create_crypto("ETH"))
1190 .quote_currency(Currency::get_or_create_crypto("USD"))
1191 .price_precision(2)
1192 .size_precision(8)
1193 .price_increment(Price::from("0.01"))
1194 .size_increment(Quantity::from("0.00000001"))
1195 .min_quantity(Quantity::from("0.00000001"))
1196 .ts_event(UnixNanos::default())
1197 .ts_init(UnixNanos::default())
1198 .build()
1199 .unwrap(),
1200 )
1201 }
1202
1203 fn capture_handler() -> FeedHandler {
1204 let mut handler = test_handler();
1205 for instrument in [btc_usd_instrument(), eth_usd_instrument()] {
1206 handler.instruments.insert(instrument.id(), instrument);
1207 }
1208 handler
1209 }
1210
1211 fn capture_frames() -> Vec<String> {
1212 load_test_fixture("ws_l2_resubscribe_capture.jsonl")
1213 .lines()
1214 .map(str::to_owned)
1215 .collect()
1216 }
1217
1218 fn handle_frame(handler: &mut FeedHandler, text: &str) -> Vec<NautilusWsMessage> {
1220 let mut output: Vec<_> = handler.handle_text(text).into_iter().collect();
1221 while let Some(msg) = handler.buffer.pop() {
1222 output.push(msg);
1223 }
1224 output
1225 }
1226
1227 fn is_gap(msg: &NautilusWsMessage) -> bool {
1228 matches!(msg, NautilusWsMessage::SequenceGap { .. })
1229 }
1230
1231 #[rstest]
1235 fn test_capture_with_mixed_channels_reports_no_sequence_gaps() {
1236 let mut handler = capture_handler();
1237 let mut snapshots = Vec::new();
1238 let mut updates = 0;
1239
1240 for frame in capture_frames() {
1241 for msg in handle_frame(&mut handler, &frame) {
1242 match msg {
1243 NautilusWsMessage::Deltas(deltas)
1244 if deltas.deltas[0].action == BookAction::Clear =>
1245 {
1246 snapshots.push(deltas.instrument_id.symbol.to_string());
1247 }
1248 NautilusWsMessage::Deltas(_) => updates += 1,
1249 NautilusWsMessage::SequenceGap { expected, received } => {
1250 panic!("false gap: expected {expected}, was {received}")
1251 }
1252 _ => {}
1253 }
1254 }
1255 }
1256
1257 assert_eq!(snapshots, ["BTC-USD", "ETH-USD", "BTC-USD"]);
1258 assert!(updates > 200, "updates={updates}");
1259 assert_eq!(handler.last_sequence_num, Some(300));
1260 }
1261
1262 #[rstest]
1263 fn test_capture_matches_subscription_setup() {
1264 let setup: Vec<serde_json::Value> =
1265 serde_json::from_str(&load_test_fixture("ws_l2_resubscribe_subscriptions.json"))
1266 .unwrap();
1267 let frames = capture_frames();
1268
1269 for step in setup {
1270 let ack = step["ack_sequence_num"].as_u64().unwrap();
1271 let frame: serde_json::Value =
1272 serde_json::from_str(&frames[usize::try_from(ack).unwrap()]).unwrap();
1273
1274 assert_eq!(frame["sequence_num"], ack);
1275 assert_eq!(frame["channel"], "subscriptions", "{step}");
1276 }
1277
1278 let snapshot: serde_json::Value = serde_json::from_str(&frames[281]).unwrap();
1280 assert_eq!(snapshot["events"][0]["type"], "snapshot");
1281 assert_eq!(snapshot["events"][0]["product_id"], "BTC-USD");
1282 }
1283
1284 #[rstest]
1285 #[case::book_update(20)]
1286 #[case::heartbeat(16)]
1287 #[case::market_trades(19)]
1288 #[case::subscription_ack(105)]
1289 fn test_skipped_envelope_reports_gap_before_next_envelope(#[case] skipped: usize) {
1290 let mut handler = capture_handler();
1291 let frames = capture_frames();
1292
1293 for frame in &frames[..skipped] {
1294 assert!(!handle_frame(&mut handler, frame).iter().any(is_gap));
1295 }
1296
1297 let output = handle_frame(&mut handler, &frames[skipped + 1]);
1298 let skipped = skipped as u64;
1299
1300 assert!(matches!(
1301 output.first(),
1302 Some(NautilusWsMessage::SequenceGap { expected, received })
1303 if *expected == skipped && *received == skipped + 1
1304 ));
1305 assert!(!output[1..].iter().any(is_gap));
1306
1307 for frame in &frames[usize::try_from(skipped).unwrap() + 2..] {
1308 assert!(!handle_frame(&mut handler, frame).iter().any(is_gap));
1309 }
1310 }
1311
1312 #[rstest]
1313 fn test_gap_precedes_deltas_of_revealing_envelope() {
1314 let mut handler = capture_handler();
1315 let frames = capture_frames();
1316 handle_frame(&mut handler, &frames[18]);
1317
1318 let output = handle_frame(&mut handler, &frames[20]);
1320
1321 assert_eq!(output.len(), 2);
1322 assert!(is_gap(&output[0]));
1323 assert!(matches!(output[1], NautilusWsMessage::Deltas(_)));
1324 }
1325
1326 #[rstest]
1327 fn test_reconnect_resets_sequence_tracking() {
1328 let mut handler = capture_handler();
1329 let frames = capture_frames();
1330
1331 for frame in &frames[..50] {
1332 handle_frame(&mut handler, frame);
1333 }
1334 assert_eq!(handler.last_sequence_num, Some(49));
1335
1336 let reconnected = handle_frame(&mut handler, RECONNECTED);
1337 assert!(matches!(reconnected[..], [NautilusWsMessage::Reconnected]));
1338 assert_eq!(handler.last_sequence_num, None);
1339
1340 for frame in &frames[..20] {
1342 assert!(!handle_frame(&mut handler, frame).iter().any(is_gap));
1343 }
1344 assert_eq!(handler.last_sequence_num, Some(19));
1345 }
1346
1347 #[rstest]
1348 fn test_unparsed_envelope_still_advances_sequence() {
1349 let mut handler = capture_handler();
1350 let frames = capture_frames();
1351 handle_frame(&mut handler, &frames[0]);
1352
1353 let unknown = r#"{"channel":"unknown","timestamp":"","sequence_num":1,"events":[]}"#;
1354 assert!(handle_frame(&mut handler, unknown).is_empty());
1355 assert!(!handle_frame(&mut handler, &frames[2]).iter().any(is_gap));
1356
1357 let skipped = r#"{"channel":"unknown","timestamp":"","sequence_num":4,"events":[]}"#;
1358 assert!(matches!(
1359 handle_frame(&mut handler, skipped)[..],
1360 [NautilusWsMessage::SequenceGap {
1361 expected: 3,
1362 received: 4
1363 }]
1364 ));
1365 }
1366
1367 #[rstest]
1368 fn test_venue_error_frame_surfaces_message_without_moving_sequence() {
1369 let mut handler = capture_handler();
1370 let frames = capture_frames();
1371 handle_frame(&mut handler, &frames[0]);
1372
1373 let output = handle_frame(
1374 &mut handler,
1375 r#"{"type":"error","message":"rate limit exceeded"}"#,
1376 );
1377
1378 assert!(matches!(
1379 &output[..],
1380 [NautilusWsMessage::Error(message)] if message == "rate limit exceeded"
1381 ));
1382 assert_eq!(handler.last_sequence_num, Some(0));
1383 assert!(!handle_frame(&mut handler, &frames[1]).iter().any(is_gap));
1384 }
1385
1386 #[rstest]
1387 fn test_signal_release_acquire_exits_handler_loop() {
1388 use std::sync::atomic::Ordering;
1389
1390 let signal = Arc::new(AtomicBool::new(false));
1391 let (_cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
1392 let (_raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
1393 let mut handler =
1394 FeedHandler::new(signal.clone(), cmd_rx, raw_rx, Arc::new(AtomicMap::new()));
1395
1396 signal.store(true, Ordering::Release);
1397
1398 let runtime = tokio::runtime::Builder::new_current_thread()
1399 .enable_all()
1400 .build()
1401 .unwrap();
1402 let result = runtime.block_on(async { handler.next().await });
1403 assert!(result.is_none(), "{result:?}");
1404 }
1405}