1use std::{
19 collections::{BTreeSet, VecDeque},
20 future::Future,
21 sync::{
22 Arc,
23 atomic::{AtomicBool, Ordering},
24 },
25};
26
27use ahash::{AHashMap, AHashSet};
28use nautilus_common::cache::fifo::FifoCache;
29use nautilus_core::{AtomicTime, Params, nanos::UnixNanos, time::get_atomic_clock_realtime};
30use nautilus_live::book::snapshot::SnapshotGate;
31use nautilus_model::{
32 data::{BarType, CustomData, Data, DataType},
33 identifiers::{AccountId, InstrumentId},
34 instruments::{Instrument, InstrumentAny},
35 types::Price,
36};
37use nautilus_network::{
38 RECONNECTED,
39 error::SendError,
40 retry::{RetryError, RetryManager, create_websocket_retry_manager},
41 websocket::{SubscriptionState, WebSocketClient},
42};
43use rust_decimal::Decimal;
44use serde::Deserialize;
45use tokio_tungstenite::tungstenite::Message;
46use tokio_util::sync::CancellationToken;
47use ustr::Ustr;
48
49use super::{
50 client::{AssetContextDataType, CloidCache},
51 enums::HyperliquidWsChannel,
52 error::HyperliquidWsError,
53 l2::CompactBook,
54 messages::{
55 CandleData, ExecutionReport, HyperliquidWsMessage, HyperliquidWsRequest, NautilusWsMessage,
56 PostRequest, SubscriptionRequest, WsActiveAssetCtxData, WsAllDexsAssetCtxsData,
57 WsCompactBookData, WsMessageHeader, WsUserEventData,
58 },
59 parse::{
60 parse_ws_asset_context, parse_ws_candle, parse_ws_fill_report, parse_ws_open_interest,
61 parse_ws_order_book_deltas, parse_ws_order_book_depth, parse_ws_order_status_report,
62 parse_ws_public_trade, parse_ws_quote_tick, parse_ws_trade_tick, parse_ws_twap_history_row,
63 parse_ws_twap_slice_fill,
64 },
65 post::PostRouter,
66 rate_limits::WebSocketRateLimits,
67 trades::TradeStreamUses,
68};
69use crate::{
70 common::consts::HEARTBEAT_INTERVAL,
71 data_types::{
72 HyperliquidAllDexsAssetCtxs, HyperliquidAllMids, HyperliquidDexAssetCtx,
73 HyperliquidImpactPrices,
74 },
75};
76
77const HEARTBEAT_MESSAGE: &str = r#"{"method":"ping"}"#;
78
79#[derive(Debug)]
81#[expect(
82 clippy::large_enum_variant,
83 reason = "Commands are ephemeral and immediately consumed"
84)]
85#[allow(private_interfaces)]
86pub enum HandlerCommand {
87 SetClient {
89 client: WebSocketClient,
90 initialized: tokio::sync::oneshot::Sender<()>,
91 },
92 Disconnect,
94 Subscribe {
96 subscriptions: Vec<SubscriptionRequest>,
97 },
98 Unsubscribe {
100 subscriptions: Vec<SubscriptionRequest>,
101 },
102 Resubscribe { subscription: SubscriptionRequest },
104 WriteBook {
110 subscription: SubscriptionRequest,
111 replace: bool,
112 cancel: CancellationToken,
113 gate: SnapshotGate,
114 completion: tokio::sync::oneshot::Sender<Result<(), HyperliquidWsError>>,
115 },
116 Post {
118 id: u64,
119 request: PostRequest,
120 deadline: tokio::time::Instant,
121 cancellation_token: CancellationToken,
122 },
123 InitializeInstruments(Vec<InstrumentAny>),
125 UpdateInstrument(InstrumentAny),
127 AddBarType { key: String, bar_type: BarType },
129 RemoveBarType { key: String },
131 UpdateAssetContextSubs {
133 coin: Ustr,
134 data_types: AHashSet<AssetContextDataType>,
135 },
136 UpdateTradeSubs { coin: Ustr, uses: TradeStreamUses },
138 CacheAllDexAssetCtxsInstrumentIds(AHashMap<Ustr, Vec<Option<InstrumentId>>>),
140 CacheSpotFillCoins(AHashMap<Ustr, Ustr>),
142 SetDepthSub { coin: Ustr, subscribed: bool },
144}
145
146#[derive(Default)]
147struct AssetContextCaches {
148 mark_price: AHashMap<Ustr, Decimal>,
149 index_price: AHashMap<Ustr, Decimal>,
150 funding_rate: AHashMap<Ustr, Decimal>,
151 open_interest: AHashMap<Ustr, Decimal>,
152}
153
154impl AssetContextCaches {
155 fn clear(&mut self, coin: Ustr, data_type: AssetContextDataType) {
156 match data_type {
157 AssetContextDataType::MarkPrice => {
158 self.mark_price.remove(&coin);
159 }
160 AssetContextDataType::IndexPrice => {
161 self.index_price.remove(&coin);
162 }
163 AssetContextDataType::FundingRate => {
164 self.funding_rate.remove(&coin);
165 }
166 AssetContextDataType::OpenInterest => {
167 self.open_interest.remove(&coin);
168 }
169 }
170 }
171
172 fn clear_removed(
173 &mut self,
174 coin: Ustr,
175 previous_data_types: Option<&AHashSet<AssetContextDataType>>,
176 next_data_types: &AHashSet<AssetContextDataType>,
177 ) {
178 let Some(previous_data_types) = previous_data_types else {
179 return;
180 };
181
182 for data_type in previous_data_types {
183 if !next_data_types.contains(data_type) {
184 self.clear(coin, *data_type);
185 }
186 }
187 }
188}
189
190#[derive(Debug)]
191struct AllMidsDataTypeCache {
192 dexes: BTreeSet<Option<String>>,
193 projected: Vec<DataType>,
194}
195
196impl Default for AllMidsDataTypeCache {
197 fn default() -> Self {
198 let mut cache = Self {
199 dexes: BTreeSet::new(),
200 projected: Vec::new(),
201 };
202 cache.rebuild();
203 cache
204 }
205}
206
207impl AllMidsDataTypeCache {
208 fn apply(&mut self, subscription: &SubscriptionRequest, subscribed: bool) {
209 let SubscriptionRequest::AllMids { dex } = subscription else {
210 return;
211 };
212 let changed = if subscribed {
213 self.dexes.insert(dex.clone())
214 } else {
215 self.dexes.remove(dex)
216 };
217
218 if changed {
219 self.rebuild();
220 }
221 }
222
223 fn as_slice(&self) -> &[DataType] {
224 &self.projected
225 }
226
227 fn rebuild(&mut self) {
228 self.projected.clear();
229 if self.dexes.is_empty() {
230 self.projected
231 .push(DataType::new("HyperliquidAllMids", None, None));
232 return;
233 }
234
235 self.projected.extend(self.dexes.iter().map(|dex| {
236 let metadata = dex.as_ref().map(|dex| {
237 Params::new([("dex".to_owned(), serde_json::Value::String(dex.clone()))].into())
238 });
239 DataType::new("HyperliquidAllMids", metadata, None)
240 }));
241 }
242}
243
244pub(super) struct FeedHandler {
245 clock: &'static AtomicTime,
246 signal: Arc<AtomicBool>,
247 client: Option<WebSocketClient>,
248 cmd_rx: tokio::sync::mpsc::UnboundedReceiver<HandlerCommand>,
249 raw_rx: tokio::sync::mpsc::UnboundedReceiver<Message>,
250 cmd_closed: bool,
251 raw_closed: bool,
252 out_tx: tokio::sync::mpsc::UnboundedSender<NautilusWsMessage>,
253 account_id: Option<AccountId>,
254 subscriptions: SubscriptionState,
255 all_mids_data_types: AllMidsDataTypeCache,
256 post_router: Arc<PostRouter>,
257 rate_limits: Arc<WebSocketRateLimits>,
258 client_id: u64,
259 heartbeat: tokio::time::Interval,
260 retry_manager: RetryManager<HyperliquidWsError>,
261 retry_manager_post: RetryManager<PostSendError>,
262 message_buffer: VecDeque<NautilusWsMessage>,
263 instruments: AHashMap<Ustr, InstrumentAny>,
264 cloid_cache: CloidCache,
265 bar_types_cache: AHashMap<String, BarType>,
266 bar_cache: AHashMap<String, CandleData>,
267 asset_context_subs: AHashMap<Ustr, AHashSet<AssetContextDataType>>,
268 trade_subs: AHashMap<Ustr, TradeStreamUses>,
269 all_dex_asset_ctxs_instrument_ids: AHashMap<Ustr, Vec<Option<InstrumentId>>>,
270 depth_subs: AHashSet<Ustr>,
271 compact_books: AHashMap<Ustr, CompactBookStream>,
272 processed_trade_ids: FifoCache<u64, 10_000>,
273 processed_public_trade_ids: FifoCache<(Ustr, u64), 10_000>,
274 asset_context_caches: AssetContextCaches,
275}
276
277impl FeedHandler {
278 #[allow(
280 clippy::too_many_arguments,
281 reason = "constructs the handler from independent runtime channels and caches"
282 )]
283 pub(super) fn new(
284 signal: Arc<AtomicBool>,
285 cmd_rx: tokio::sync::mpsc::UnboundedReceiver<HandlerCommand>,
286 raw_rx: tokio::sync::mpsc::UnboundedReceiver<Message>,
287 out_tx: tokio::sync::mpsc::UnboundedSender<NautilusWsMessage>,
288 account_id: Option<AccountId>,
289 subscriptions: SubscriptionState,
290 cloid_cache: CloidCache,
291 post_router: Arc<PostRouter>,
292 rate_limits: Arc<WebSocketRateLimits>,
293 client_id: u64,
294 ) -> Self {
295 let heartbeat = tokio::time::interval_at(
296 tokio::time::Instant::now() + HEARTBEAT_INTERVAL,
297 HEARTBEAT_INTERVAL,
298 );
299 Self {
300 clock: get_atomic_clock_realtime(),
301 signal,
302 client: None,
303 cmd_rx,
304 raw_rx,
305 cmd_closed: false,
306 raw_closed: false,
307 out_tx,
308 account_id,
309 subscriptions,
310 all_mids_data_types: AllMidsDataTypeCache::default(),
311 post_router,
312 rate_limits,
313 client_id,
314 heartbeat,
315 retry_manager: create_websocket_retry_manager(),
316 retry_manager_post: create_websocket_retry_manager(),
317 message_buffer: VecDeque::new(),
318 instruments: AHashMap::new(),
319 cloid_cache,
320 bar_types_cache: AHashMap::new(),
321 bar_cache: AHashMap::new(),
322 asset_context_subs: AHashMap::new(),
323 trade_subs: AHashMap::new(),
324 all_dex_asset_ctxs_instrument_ids: AHashMap::new(),
325 depth_subs: AHashSet::new(),
326 compact_books: AHashMap::new(),
327 processed_trade_ids: FifoCache::new(),
328 processed_public_trade_ids: FifoCache::new(),
329 asset_context_caches: AssetContextCaches::default(),
330 }
331 }
332
333 pub(super) fn send(&self, msg: NautilusWsMessage) -> Result<(), String> {
335 self.out_tx
336 .send(msg)
337 .map_err(|e| format!("Failed to send message: {e}"))
338 }
339
340 pub(super) fn is_stopped(&self) -> bool {
342 self.signal.load(Ordering::Relaxed)
343 }
344
345 async fn send_with_retry(&self, payload: String) -> anyhow::Result<()> {
346 if let Some(client) = &self.client {
347 let rate_key = self.rate_limits.message_key();
348 self.retry_manager
349 .invocation(
350 "websocket_send",
351 || {
352 let payload = payload.clone();
353 async move {
354 client
355 .send_text(payload, Some(std::slice::from_ref(&rate_key)))
356 .await
357 .map_err(|e| {
358 HyperliquidWsError::ClientError(format!("Send failed: {e}"))
359 })
360 }
361 },
362 should_retry_hyperliquid_error,
363 |e| create_hyperliquid_timeout_error(e.to_string()),
364 )
365 .execute()
366 .await
367 .map_err(|e| anyhow::anyhow!("{e}"))
368 } else {
369 Err(anyhow::anyhow!("No WebSocket client available"))
370 }
371 }
372
373 pub(super) async fn next(&mut self) -> Option<NautilusWsMessage> {
374 if let Some(msg) = self.message_buffer.pop_front() {
375 return Some(msg);
376 }
377
378 loop {
379 if self.raw_closed && self.cmd_rx.is_empty() {
380 log::debug!("Handler shutting down: input stream closed");
381 return None;
382 }
383
384 tokio::select! {
385 cmd = self.cmd_rx.recv(), if !self.cmd_closed => {
386 let Some(cmd) = cmd else {
387 self.cmd_closed = true;
388 continue;
389 };
390
391 match cmd {
392 HandlerCommand::SetClient { client, initialized } => {
393 log::debug!("Setting WebSocket client in handler");
394 self.client = Some(client);
395 let _ = initialized.send(());
396 }
397 HandlerCommand::Disconnect => {
398 log::debug!("Handler received disconnect command");
399
400 if let Some(ref client) = self.client {
401 self.rate_limits.acquire_message().await;
402 client.disconnect().await;
403 }
404 self.signal.store(true, Ordering::SeqCst);
405 return None;
406 }
407 HandlerCommand::Subscribe { subscriptions } => {
408 self.subscribe(subscriptions).await;
409 }
410 HandlerCommand::Unsubscribe { subscriptions } => {
411 self.unsubscribe(subscriptions).await;
412 }
413 HandlerCommand::Resubscribe { subscription } => {
414 self.unsubscribe(vec![subscription.clone()]).await;
415 self.subscribe(vec![subscription]).await;
416 }
417 HandlerCommand::WriteBook {
418 subscription,
419 replace,
420 cancel,
421 gate,
422 completion,
423 } => {
424 let result = self.write_book(subscription, replace).await;
428
429 if result.is_ok() && !cancel.is_cancelled() {
430 gate.open();
431 }
432 let _ = completion.send(result);
433 }
434 HandlerCommand::Post {
435 id,
436 request,
437 deadline,
438 cancellation_token,
439 } => {
440 if cancellation_token.is_cancelled()
441 || tokio::time::Instant::now() >= deadline
442 {
443 self.post_router
444 .cancel_registration(id, &cancellation_token)
445 .await;
446 continue;
447 }
448
449 let request = HyperliquidWsRequest::Post { id, request };
450 match serde_json::to_string(&request) {
451 Ok(payload) => {
452 log::debug!("Sending post payload: id={id}");
453 let result = if let Some(client) = &self.client {
454 let rate_key = self.rate_limits.message_key();
455 send_post_with_retry(
456 &self.retry_manager_post,
457 deadline,
458 &cancellation_token,
459 || {
460 let payload = payload.clone();
461 async move {
462 let connection_epoch =
463 client.connection_epoch();
464 client
465 .send_text_on_connection(
466 payload,
467 Some(std::slice::from_ref(&rate_key)),
468 connection_epoch,
469 )
470 .await
471 .map_err(PostSendError::Transport)
472 }
473 },
474 )
475 .await
476 .map_err(|e| anyhow::anyhow!("{e}"))
477 } else {
478 Err(anyhow::anyhow!("No WebSocket client available"))
479 };
480
481 if let Err(e) = result {
482 log::warn!("Error sending post request id={id}: {e}");
483 self.post_router
484 .cancel_registration(id, &cancellation_token)
485 .await;
486 }
487 }
488 Err(e) => {
489 log::error!("Error serializing post request id={id}: {e}");
490 self.post_router
491 .cancel_registration(id, &cancellation_token)
492 .await;
493 }
494 }
495 }
496 HandlerCommand::InitializeInstruments(instruments) => {
497 for inst in instruments {
498 let coin = inst.raw_symbol().inner();
499 self.instruments.insert(coin, inst);
500 }
501 }
502 HandlerCommand::UpdateInstrument(inst) => {
503 let coin = inst.raw_symbol().inner();
504 self.instruments.insert(coin, inst);
505 }
506 HandlerCommand::AddBarType { key, bar_type } => {
507 self.bar_types_cache.insert(key, bar_type);
508 }
509 HandlerCommand::RemoveBarType { key } => {
510 self.bar_types_cache.remove(&key);
511 self.bar_cache.remove(&key);
512 }
513 HandlerCommand::UpdateAssetContextSubs { coin, data_types } => {
514 let previous_data_types = self.asset_context_subs.get(&coin).cloned();
515 self.asset_context_caches.clear_removed(
516 coin,
517 previous_data_types.as_ref(),
518 &data_types,
519 );
520
521 if data_types.is_empty() {
522 self.asset_context_subs.remove(&coin);
523 } else {
524 self.asset_context_subs.insert(coin, data_types);
525 }
526 }
527 HandlerCommand::UpdateTradeSubs { coin, uses } => {
528 if uses.is_empty() {
529 self.trade_subs.remove(&coin);
530 } else {
531 self.trade_subs.insert(coin, uses);
532 }
533 }
534 HandlerCommand::CacheAllDexAssetCtxsInstrumentIds(mappings) => {
535 self.all_dex_asset_ctxs_instrument_ids.extend(mappings);
538 }
539 HandlerCommand::CacheSpotFillCoins(_) => {
540 }
542 HandlerCommand::SetDepthSub { coin, subscribed } => {
543 if subscribed {
544 self.depth_subs.insert(coin);
545 } else {
546 self.depth_subs.remove(&coin);
547 }
548 }
549 }
550 }
551
552 raw_msg = self.raw_rx.recv(), if !self.raw_closed => {
553 let Some(raw_msg) = raw_msg else {
554 self.raw_closed = true;
555 continue;
556 };
557
558 match raw_msg {
559 Message::Text(text) => {
560 if text == RECONNECTED {
561 self.compact_books.clear();
562 log::info!("Received RECONNECTED sentinel");
563 return Some(NautilusWsMessage::Reconnected);
564 }
565
566 let context = FrameContext {
567 client_id: self.client_id,
568 payload_bytes: text.len(),
569 };
570
571 match super::messages::decode_ws_message(&text) {
572 Ok(msg) => {
573 if let HyperliquidWsMessage::Post { data } = msg {
574 self.post_router.complete(data).await;
575 continue;
576 }
577
578 if let HyperliquidWsMessage::SubscriptionResponse { data } = &msg {
579 self.confirm_compact_request(&data.subscription, &data.method);
580 let key = subscription_response_key(&data.subscription, &self.subscriptions);
581 match data.method.as_str() {
582 "subscribe" => self.subscriptions.confirm_subscribe(&key),
583 "unsubscribe" => {
584 let was_pending = self
585 .subscriptions
586 .pending_unsubscribe_topics()
587 .iter()
588 .any(|topic| topic == &key);
589 self.subscriptions.confirm_unsubscribe(&key);
590
591 if was_pending {
592 self.rate_limits.release_subscription(
593 self.client_id,
594 &key,
595 );
596 }
597 }
598 _ => {
599 context.log_conversion_error("subscription_response", log::Level::Warn);
600 }
601 }
602 continue;
603 }
604
605 let ts_init = self.clock.get_time_ns();
606
607 if let HyperliquidWsMessage::L2 { data } = msg {
608 if let Some(message) = self.handle_compact_book(data, ts_init) {
609 return Some(message);
610 }
611 continue;
612 }
613
614 if matches!(&msg, HyperliquidWsMessage::Error { .. })
615 && self.compact_books.values().any(|stream| !stream.pending.is_empty())
616 {
617 self.invalidate_compact_books();
619 }
620
621 let nautilus_msgs = Self::parse_to_nautilus_messages(
622 msg,
623 context,
624 &self.instruments,
625 &self.cloid_cache,
626 &self.bar_types_cache,
627 self.account_id,
628 ts_init,
629 &self.asset_context_subs,
630 &self.trade_subs,
631 &self.depth_subs,
632 &mut self.processed_trade_ids,
633 &mut self.processed_public_trade_ids,
634 &mut self.asset_context_caches,
635 &mut self.bar_cache,
636 &self.all_dex_asset_ctxs_instrument_ids,
637 self.all_mids_data_types.as_slice(),
638 );
639
640 if !nautilus_msgs.is_empty() {
641 let mut iter = nautilus_msgs.into_iter();
642 let first = iter.next().unwrap();
643 self.message_buffer.extend(iter);
644 return Some(first);
645 }
646 }
647 Err(e) => {
648 context.log_decode_error(&text, &e);
649 if serde_json::from_str::<WsMessageHeader<'_>>(&text)
650 .is_ok_and(|header| header.channel == "l2")
651 {
652 self.invalidate_compact_books();
653 }
654 }
655 }
656 }
657 Message::Ping(data) => {
658 if let Some(ref client) = self.client {
659 self.rate_limits.acquire_message().await;
660
661 if let Err(e) = client.send_pong(data.to_vec()).await {
662 log::error!("Error sending pong: {e}");
663 }
664 }
665 }
666 Message::Close(_) => {
667 log::debug!("Received WebSocket close frame");
668 return None;
669 }
670 _ => {}
671 }
672 }
673
674 _ = self.heartbeat.tick() => {
675 if self.client.as_ref().is_some_and(WebSocketClient::is_active)
676 && let Err(e) = self.send_with_retry(
677 HEARTBEAT_MESSAGE.to_string(),
678 ).await
679 {
680 log::error!("Error sending WebSocket heartbeat: {e}");
681 }
682 }
683
684 }
685 }
686 }
687
688 fn prepare_compact_request(&mut self, request: &HyperliquidWsRequest) -> Option<Ustr> {
689 let (subscription, subscribe) = match request {
690 HyperliquidWsRequest::Subscribe { subscription } => (subscription, true),
691 HyperliquidWsRequest::Unsubscribe { subscription } => (subscription, false),
692 _ => return None,
693 };
694 let SubscriptionRequest::L2 { coin, .. } = subscription else {
695 return None;
696 };
697 let stream = self.compact_books.entry(*coin).or_default();
698 stream.output_gate.lock().close();
700 stream.output_gate = SnapshotGate::default();
701 stream.book = None;
702 stream.confirmed = false;
703 stream.desired = subscribe;
704
705 if subscribe {
706 stream.generation = stream.generation.wrapping_add(1);
707 }
708
709 stream.pending.push_back((subscribe, stream.generation));
710 Some(*coin)
711 }
712
713 fn compact_write_failed(&mut self, coin: Option<Ustr>) {
714 if let Some(coin) = coin
715 && let Some(stream) = self.compact_books.get_mut(&coin)
716 {
717 stream.pending.pop_back();
718 }
719 }
720
721 fn confirm_compact_request(&mut self, subscription: &SubscriptionRequest, method: &str) {
722 let SubscriptionRequest::L2 { coin, .. } = subscription else {
723 return;
724 };
725 let Some(stream) = self.compact_books.get_mut(coin) else {
726 return;
727 };
728 let subscribe = match method {
729 "subscribe" => true,
730 "unsubscribe" => false,
731 _ => return,
732 };
733 let Some(&(expected, generation)) = stream.pending.front() else {
734 return;
735 };
736
737 if subscribe != expected {
738 return;
739 }
740
741 stream.pending.pop_front();
742
743 if subscribe && generation == stream.generation && stream.desired {
745 stream.confirmed = self.subscriptions.is_subscribed(&Ustr::from("l2"), coin);
746 }
747
748 if !stream.desired && stream.pending.is_empty() {
749 self.compact_books.remove(coin);
750 }
751 }
752
753 fn invalidate_compact_books(&mut self) {
754 self.compact_books.clear();
755
756 if let Some(client) = &self.client {
758 let _ = client.request_reconnect();
759 }
760 }
761
762 fn handle_compact_book(
763 &mut self,
764 data: WsCompactBookData,
765 ts_init: UnixNanos,
766 ) -> Option<NautilusWsMessage> {
767 let (coin, is_snapshot) = match &data {
768 WsCompactBookData::Snapshot(book) => (book.coin, true),
769 WsCompactBookData::Update(update) => (update.coin, false),
770 };
771 let stream = self.compact_books.get_mut(&coin)?;
772
773 if !stream.confirmed || !stream.desired {
774 return None;
775 }
776
777 let instrument = self.instruments.get(&coin)?;
778
779 let result = (|| -> anyhow::Result<Option<NautilusWsMessage>> {
780 match data {
781 WsCompactBookData::Snapshot(book) => stream.book = Some(CompactBook::new(book)),
782 WsCompactBookData::Update(update) => {
783 let Some(book) = &mut stream.book else {
784 return Ok(None);
785 };
786 book.apply(update)?;
787 }
788 }
789
790 let Some(book) = &stream.book else {
791 return Ok(None);
792 };
793 let deltas = parse_ws_order_book_deltas(&book.data, instrument, ts_init)?;
794 let depth = self
795 .depth_subs
796 .contains(&coin)
797 .then(|| parse_ws_order_book_depth(&book.data, instrument, ts_init))
798 .transpose()?
799 .map(Box::new);
800 Ok(Some(NautilusWsMessage::CompactBook {
801 deltas,
802 depth,
803 is_snapshot,
804 output_gate: stream.output_gate.clone(),
805 }))
806 })();
807
808 match result {
809 Ok(message) => message,
810 Err(e) => {
811 stream.book = None;
812 stream.confirmed = false;
813 log::warn!("Invalid compact book for {}: {e}", instrument.id());
814 Some(NautilusWsMessage::BookInvalid {
815 instrument_id: instrument.id(),
816 output_gate: Some(stream.output_gate.clone()),
817 })
818 }
819 }
820 }
821
822 async fn subscribe(&mut self, subscriptions: Vec<SubscriptionRequest>) {
823 for subscription in subscriptions {
824 let key = subscription_to_key(&subscription);
825 self.subscriptions.mark_subscribe(&key);
826
827 if let Err(e) = self
828 .rate_limits
829 .reserve_subscription(self.client_id, &subscription)
830 {
831 log::error!("Cannot subscribe to {key}: {e}");
832 self.subscriptions.mark_unsubscribe(&key);
833 self.subscriptions.confirm_unsubscribe(&key);
834 continue;
835 }
836
837 self.all_mids_data_types.apply(&subscription, true);
838 let request = HyperliquidWsRequest::Subscribe { subscription };
839 match serde_json::to_string(&request) {
840 Ok(payload) => {
841 log::debug!("Sending subscribe payload ({} bytes)", payload.len());
842 let compact = self.prepare_compact_request(&request);
843 if let Err(e) = self.send_with_retry(payload).await {
844 self.compact_write_failed(compact);
845 log::error!("Error subscribing to {key}: {e}");
846 self.subscriptions.mark_failure(&key);
847 }
848 }
849 Err(e) => {
850 log::error!("Error serializing subscription for {key}: {e}");
851 self.subscriptions.mark_failure(&key);
852 }
853 }
854 }
855 }
856
857 async fn send_book_request(
858 &mut self,
859 request: &HyperliquidWsRequest,
860 rate_keys: Option<&[Ustr]>,
861 epoch: u64,
862 ) -> Result<(), HyperliquidWsError> {
863 let payload = serialize_request(request)?;
864 let compact = self.prepare_compact_request(request);
865 let result = match &self.client {
866 Some(client) => client
867 .send_text_on_connection(payload, rate_keys, epoch)
868 .await
869 .map_err(HyperliquidWsError::from),
870 None => Err(HyperliquidWsError::ClientError(
871 "No WebSocket client available".to_string(),
872 )),
873 };
874
875 if result.is_err() {
876 self.compact_write_failed(compact);
877 }
878 result
879 }
880
881 async fn write_book(
882 &mut self,
883 subscription: SubscriptionRequest,
884 replace: bool,
885 ) -> Result<(), HyperliquidWsError> {
886 let epoch = self
887 .client
888 .as_ref()
889 .ok_or_else(|| {
890 HyperliquidWsError::ClientError("No WebSocket client available".to_string())
891 })?
892 .connection_epoch();
893
894 let key = subscription_to_key(&subscription);
895 let rate_key = self.rate_limits.message_key();
896 let rate_keys = Some(std::slice::from_ref(&rate_key));
897
898 if replace {
899 self.subscriptions.mark_failure(&key);
901
902 let request = HyperliquidWsRequest::Unsubscribe {
903 subscription: subscription.clone(),
904 };
905 self.send_book_request(&request, rate_keys, epoch).await?;
906 } else {
907 self.subscriptions.mark_subscribe(&key);
908
909 if let Err(e) = self
910 .rate_limits
911 .reserve_subscription(self.client_id, &subscription)
912 {
913 self.subscriptions.mark_unsubscribe(&key);
914 self.subscriptions.confirm_unsubscribe(&key);
915 return Err(HyperliquidWsError::ClientError(e));
916 }
917 }
918
919 let request = HyperliquidWsRequest::Subscribe { subscription };
920 if let Err(e) = self.send_book_request(&request, rate_keys, epoch).await {
921 self.subscriptions.mark_failure(&key);
922 return Err(e);
923 }
924
925 Ok(())
926 }
927
928 async fn unsubscribe(&mut self, subscriptions: Vec<SubscriptionRequest>) {
929 for subscription in subscriptions {
930 let key = subscription_to_key(&subscription);
931 self.subscriptions.mark_unsubscribe(&key);
932 self.all_mids_data_types.apply(&subscription, false);
933
934 let request = HyperliquidWsRequest::Unsubscribe { subscription };
935 match serde_json::to_string(&request) {
936 Ok(payload) => {
937 log::debug!("Sending unsubscribe payload ({} bytes)", payload.len());
938 let compact = self.prepare_compact_request(&request);
939 if let Err(e) = self.send_with_retry(payload).await {
940 self.compact_write_failed(compact);
941 log::error!("Error unsubscribing from {key}: {e}");
942 }
943 }
944 Err(e) => {
945 log::error!("Error serializing unsubscription for {key}: {e}");
946 }
947 }
948 }
949 }
950
951 #[expect(clippy::too_many_arguments)]
952 fn parse_to_nautilus_messages(
953 msg: HyperliquidWsMessage,
954 context: FrameContext,
955 instruments: &AHashMap<Ustr, InstrumentAny>,
956 cloid_cache: &CloidCache,
957 bar_types: &AHashMap<String, BarType>,
958 account_id: Option<AccountId>,
959 ts_init: UnixNanos,
960 asset_context_subs: &AHashMap<Ustr, AHashSet<AssetContextDataType>>,
961 trade_subs: &AHashMap<Ustr, TradeStreamUses>,
962 depth_subs: &AHashSet<Ustr>,
963 processed_trade_ids: &mut FifoCache<u64, 10_000>,
964 processed_public_trade_ids: &mut FifoCache<(Ustr, u64), 10_000>,
965 asset_context_caches: &mut AssetContextCaches,
966 bar_cache: &mut AHashMap<String, CandleData>,
967 all_dex_asset_ctxs_instrument_ids: &AHashMap<Ustr, Vec<Option<InstrumentId>>>,
968 all_mids_data_types: &[DataType],
969 ) -> Vec<NautilusWsMessage> {
970 let mut result = Vec::new();
971
972 match msg {
973 HyperliquidWsMessage::ClearinghouseState { data } => {
974 result.push(NautilusWsMessage::ClearinghouseState(
975 data.clearinghouse_state,
976 ));
977 }
978 HyperliquidWsMessage::SpotState { data } => {
979 result.push(NautilusWsMessage::SpotState(data.spot_state));
980 }
981 HyperliquidWsMessage::OrderUpdates { data } => {
982 if let Some(account_id) = account_id
983 && let Some(msg) = Self::handle_order_updates(
984 &data,
985 context,
986 instruments,
987 cloid_cache,
988 account_id,
989 ts_init,
990 )
991 {
992 result.push(msg);
993 }
994 }
995 HyperliquidWsMessage::UserEvents { data } | HyperliquidWsMessage::User { data } => {
996 match data {
998 WsUserEventData::Fills { fills } => {
999 log::debug!("Received {} fill(s) from userEvents channel", fills.len());
1000
1001 if let Some(account_id) = account_id {
1002 if let Some(msg) = Self::handle_user_fills(
1003 &fills,
1004 context,
1005 instruments,
1006 cloid_cache,
1007 account_id,
1008 ts_init,
1009 processed_trade_ids,
1010 ) {
1011 log::debug!("Successfully created fill message");
1012 result.push(msg);
1013 } else {
1014 log::debug!("handle_user_fills returned None (no new fills)");
1015 }
1016 } else {
1017 log::warn!("Cannot process fills: account_id is None");
1018 }
1019 }
1020 WsUserEventData::Liquidation { liquidation } => {
1021 log::warn!(
1022 "Liquidation event: lid={}, liquidator={}, liquidated_user={}, ntl_pos={}, account_value={}",
1023 liquidation.lid,
1024 liquidation.liquidator,
1025 liquidation.liquidated_user,
1026 liquidation.liquidated_ntl_pos,
1027 liquidation.liquidated_account_value,
1028 );
1029 }
1030 _ => {
1031 log::debug!("Received non-fill user event: {data:?}");
1032 }
1033 }
1034 }
1035 HyperliquidWsMessage::UserFills { data } => {
1036 if let Some(account_id) = account_id
1039 && let Some(msg) = Self::handle_user_fills(
1040 &data.fills,
1041 context,
1042 instruments,
1043 cloid_cache,
1044 account_id,
1045 ts_init,
1046 processed_trade_ids,
1047 )
1048 {
1049 result.push(msg);
1050 }
1051 }
1052 HyperliquidWsMessage::Trades { data } => {
1053 result.extend(Self::handle_trades(
1054 &data,
1055 instruments,
1056 trade_subs,
1057 processed_public_trade_ids,
1058 ts_init,
1059 ));
1060 }
1061 HyperliquidWsMessage::AllMids { data } => {
1062 let mut mids = std::collections::HashMap::with_capacity(
1063 data.mids.len().min(instruments.len()),
1064 );
1065
1066 for (coin, mid_str) in &data.mids {
1067 if let Some(instrument) = instruments.get(coin) {
1068 match mid_str.parse::<Price>() {
1069 Ok(price) => {
1070 mids.insert(instrument.id(), price);
1071 }
1072 Err(e) => {
1073 log::warn!("Failed to parse mid price for {coin}: {e}");
1074 }
1075 }
1076 } else {
1077 log::debug!("No instrument found for coin: {coin}");
1078 }
1079 }
1080
1081 if !mids.is_empty() {
1082 let last_idx = all_mids_data_types.len().saturating_sub(1);
1084 for (i, data_type) in all_mids_data_types.iter().enumerate() {
1085 let mids_for_this = if i == last_idx {
1086 std::mem::take(&mut mids)
1087 } else {
1088 mids.clone()
1089 };
1090 let all_mids = HyperliquidAllMids::new(mids_for_this, ts_init, ts_init);
1091 result.push(NautilusWsMessage::CustomData(Data::Custom(
1092 CustomData::new(Arc::new(all_mids), data_type.clone()),
1093 )));
1094 }
1095 }
1096 }
1097 HyperliquidWsMessage::AllDexsAssetCtxs { data } => {
1098 if let Some(msg) = Self::handle_all_dexs_asset_ctxs(
1099 data,
1100 all_dex_asset_ctxs_instrument_ids,
1101 ts_init,
1102 ) {
1103 result.push(msg);
1104 }
1105 }
1106 HyperliquidWsMessage::Bbo { data } => {
1107 if let Some(msg) = Self::handle_bbo(&data, instruments, ts_init) {
1108 result.push(msg);
1109 }
1110 }
1111 HyperliquidWsMessage::L2Book { data } => {
1112 result.extend(Self::handle_l2_book(
1113 &data,
1114 instruments,
1115 depth_subs,
1116 ts_init,
1117 ));
1118 }
1119 HyperliquidWsMessage::Candle { data } => {
1120 if let Some(msg) =
1121 Self::handle_candle(&data, instruments, bar_types, bar_cache, ts_init)
1122 {
1123 result.push(msg);
1124 }
1125 }
1126 HyperliquidWsMessage::ActiveAssetCtx { data }
1127 | HyperliquidWsMessage::ActiveSpotAssetCtx { data } => {
1128 result.extend(Self::handle_asset_context(
1129 &data,
1130 instruments,
1131 asset_context_subs,
1132 asset_context_caches,
1133 ts_init,
1134 ));
1135 }
1136 HyperliquidWsMessage::UserTwapHistory { data } => {
1137 result.extend(Self::handle_user_twap_history(
1138 &data,
1139 context,
1140 instruments,
1141 ts_init,
1142 ));
1143 }
1144 HyperliquidWsMessage::UserTwapSliceFills { data } => {
1145 result.extend(Self::handle_user_twap_slice_fills(
1146 &data,
1147 context,
1148 instruments,
1149 ts_init,
1150 ));
1151 }
1152 HyperliquidWsMessage::Error { data } => {
1153 log::warn!("Received error from Hyperliquid WebSocket: {data}");
1154 }
1155 _ => {}
1157 }
1158
1159 result
1160 }
1161
1162 fn handle_order_updates(
1163 data: &[super::messages::WsOrderData],
1164 context: FrameContext,
1165 instruments: &AHashMap<Ustr, InstrumentAny>,
1166 cloid_cache: &CloidCache,
1167 account_id: AccountId,
1168 ts_init: UnixNanos,
1169 ) -> Option<NautilusWsMessage> {
1170 let mut exec_reports = Vec::new();
1171
1172 for order_update in data {
1173 let instrument = instruments.get(&order_update.order.coin);
1174
1175 if let Some(instrument) = instrument {
1176 match parse_ws_order_status_report(order_update, instrument, account_id, ts_init) {
1177 Ok(mut report) => {
1178 if let Some(cloid) = &order_update.order.cloid {
1180 let cloid_ustr = Ustr::from(cloid.as_str());
1181 let resolved = cloid_cache.lock().get(&cloid_ustr).copied();
1182
1183 if let Some(real_client_order_id) = resolved {
1184 log::debug!("Resolved cloid {cloid} -> {real_client_order_id}");
1185 report.client_order_id = Some(real_client_order_id);
1186 }
1187 }
1188 exec_reports.push(ExecutionReport::Order(report));
1189 }
1190 Err(_) => {
1191 context.log_conversion_error("order_update", log::Level::Error);
1192 }
1193 }
1194 } else {
1195 context.log_conversion_error("order_instrument", log::Level::Debug);
1196 }
1197 }
1198
1199 if exec_reports.is_empty() {
1200 None
1201 } else {
1202 Some(NautilusWsMessage::ExecutionReports(exec_reports))
1203 }
1204 }
1205
1206 fn handle_user_fills(
1207 fills: &[super::messages::WsFillData],
1208 context: FrameContext,
1209 instruments: &AHashMap<Ustr, InstrumentAny>,
1210 cloid_cache: &CloidCache,
1211 account_id: AccountId,
1212 ts_init: UnixNanos,
1213 processed_trade_ids: &mut FifoCache<u64, 10_000>,
1214 ) -> Option<NautilusWsMessage> {
1215 let mut exec_reports = Vec::new();
1216
1217 for fill in fills {
1218 if processed_trade_ids.contains(&fill.tid) {
1219 log::debug!("Skipping duplicate fill: tid={}", fill.tid);
1220 continue;
1221 }
1222
1223 let instrument = instruments.get(&fill.coin);
1224 if let Some(instrument) = instrument {
1225 match parse_ws_fill_report(fill, instrument, account_id, ts_init) {
1226 Ok(mut report) => {
1227 processed_trade_ids.add(fill.tid);
1229
1230 if let Some(cloid) = &fill.cloid {
1231 let cloid_ustr = Ustr::from(cloid.as_str());
1232 let resolved = cloid_cache.lock().get(&cloid_ustr).copied();
1233
1234 if let Some(real_client_order_id) = resolved {
1235 log::debug!(
1236 "Resolved fill cloid {cloid} -> {real_client_order_id}"
1237 );
1238 report.client_order_id = Some(real_client_order_id);
1239 }
1240 }
1241 log::debug!(
1242 "Parsed fill report: venue_order_id={:?}, trade_id={:?}",
1243 report.venue_order_id,
1244 report.trade_id
1245 );
1246 exec_reports.push(ExecutionReport::Fill(report));
1247 }
1248 Err(_) => {
1249 context.log_conversion_error("fill", log::Level::Error);
1250 }
1251 }
1252 } else {
1253 context.log_conversion_error("fill_instrument", log::Level::Warn);
1255 }
1256 }
1257
1258 if exec_reports.is_empty() {
1259 None
1260 } else {
1261 Some(NautilusWsMessage::ExecutionReports(exec_reports))
1262 }
1263 }
1264
1265 fn handle_trades(
1266 data: &[super::messages::WsTradeData],
1267 instruments: &AHashMap<Ustr, InstrumentAny>,
1268 trade_subs: &AHashMap<Ustr, TradeStreamUses>,
1269 processed_public_trade_ids: &mut FifoCache<(Ustr, u64), 10_000>,
1270 ts_init: UnixNanos,
1271 ) -> Vec<NautilusWsMessage> {
1272 let mut trade_ticks = Vec::new();
1273 let mut public_trades = Vec::new();
1274
1275 for trade in data {
1276 if let Some(instrument) = instruments.get(&trade.coin) {
1277 let uses = trade_subs.get(&trade.coin).copied().unwrap_or_default();
1278
1279 if uses.ticks {
1280 match parse_ws_trade_tick(trade, instrument, ts_init) {
1281 Ok(tick) => trade_ticks.push(tick),
1282 Err(e) => {
1283 log::error!("Error parsing trade tick: {e}");
1284 }
1285 }
1286 }
1287
1288 if uses.public_trades {
1289 let trade_key = (trade.coin, trade.tid);
1290 if processed_public_trade_ids.contains(&trade_key) {
1291 log::debug!(
1292 "Skipping replayed public trade: coin={}, tid={}",
1293 trade.coin,
1294 trade.tid
1295 );
1296 continue;
1297 }
1298
1299 match parse_ws_public_trade(trade, instrument, ts_init) {
1300 Ok(trade) => {
1301 processed_public_trade_ids.add(trade_key);
1302 public_trades.push(trade);
1303 }
1304 Err(e) => {
1305 log::error!("Error parsing public trade: {e}");
1306 }
1307 }
1308 }
1309 } else {
1310 log::debug!("No instrument found for coin: {}", trade.coin);
1311 }
1312 }
1313
1314 let mut result = Vec::with_capacity(1 + public_trades.len());
1315 if !trade_ticks.is_empty() {
1316 result.push(NautilusWsMessage::Trades(trade_ticks));
1317 }
1318 result.extend(public_trades.into_iter().map(|trade| {
1319 let instrument_id = trade.instrument_id;
1320 NautilusWsMessage::CustomData(Data::Custom(CustomData::new(
1321 Arc::new(trade),
1322 Self::public_trade_data_type(instrument_id),
1323 )))
1324 }));
1325 result
1326 }
1327
1328 fn handle_bbo(
1329 data: &super::messages::WsBboData,
1330 instruments: &AHashMap<Ustr, InstrumentAny>,
1331 ts_init: UnixNanos,
1332 ) -> Option<NautilusWsMessage> {
1333 if let Some(instrument) = instruments.get(&data.coin) {
1334 match parse_ws_quote_tick(data, instrument, ts_init) {
1335 Ok(quote_tick) => Some(NautilusWsMessage::Quote(quote_tick)),
1336 Err(e) => {
1337 log::error!("Error parsing quote tick: {e}");
1338 None
1339 }
1340 }
1341 } else {
1342 log::debug!("No instrument found for coin: {}", data.coin);
1343 None
1344 }
1345 }
1346
1347 fn handle_l2_book(
1348 data: &super::messages::WsBookData,
1349 instruments: &AHashMap<Ustr, InstrumentAny>,
1350 depth_subs: &AHashSet<Ustr>,
1351 ts_init: UnixNanos,
1352 ) -> Vec<NautilusWsMessage> {
1353 let mut out = Vec::new();
1354
1355 let Some(instrument) = instruments.get(&data.coin) else {
1356 log::debug!("No instrument found for coin: {}", data.coin);
1357 return out;
1358 };
1359
1360 match parse_ws_order_book_deltas(data, instrument, ts_init) {
1361 Ok(deltas) => out.push(NautilusWsMessage::Deltas(deltas)),
1362 Err(e) => {
1363 log::error!("Error parsing order book deltas: {e}");
1364 out.push(NautilusWsMessage::BookInvalid {
1365 instrument_id: instrument.id(),
1366 output_gate: None,
1367 });
1368 }
1369 }
1370
1371 if depth_subs.contains(&data.coin) {
1372 match parse_ws_order_book_depth(data, instrument, ts_init) {
1373 Ok(depth) => out.push(NautilusWsMessage::Depth(Box::new(depth))),
1374 Err(e) => log::error!("Error parsing order book depth: {e}"),
1375 }
1376 }
1377
1378 out
1379 }
1380
1381 fn handle_candle(
1382 data: &CandleData,
1383 instruments: &AHashMap<Ustr, InstrumentAny>,
1384 bar_types: &AHashMap<String, BarType>,
1385 bar_cache: &mut AHashMap<String, CandleData>,
1386 ts_init: UnixNanos,
1387 ) -> Option<NautilusWsMessage> {
1388 let key = format!("candle:{}:{}", data.s, data.i);
1389
1390 let mut closed_bar = None;
1391
1392 if let Some(cached) = bar_cache.get(&key) {
1393 if cached.close_time != data.close_time {
1395 log::debug!(
1396 "Bar period changed for {}: prev_close_time={}, new_close_time={}",
1397 data.s,
1398 cached.close_time,
1399 data.close_time
1400 );
1401 closed_bar = Some(cached.clone());
1402 }
1403 }
1404
1405 bar_cache.insert(key.clone(), data.clone());
1406
1407 if let Some(closed_data) = closed_bar {
1408 if let Some(bar_type) = bar_types.get(&key) {
1409 if let Some(instrument) = instruments.get(&data.s) {
1410 match parse_ws_candle(&closed_data, instrument, bar_type, ts_init) {
1411 Ok(bar) => return Some(NautilusWsMessage::Candle(bar)),
1412 Err(e) => {
1413 log::error!("Error parsing closed candle: {e}");
1414 }
1415 }
1416 } else {
1417 log::debug!("No instrument found for coin: {}", data.s);
1418 }
1419 } else {
1420 log::debug!("No bar type found for key: {key}");
1421 }
1422 }
1423
1424 None
1425 }
1426
1427 fn handle_asset_context(
1428 data: &WsActiveAssetCtxData,
1429 instruments: &AHashMap<Ustr, InstrumentAny>,
1430 asset_context_subs: &AHashMap<Ustr, AHashSet<AssetContextDataType>>,
1431 asset_context_caches: &mut AssetContextCaches,
1432 ts_init: UnixNanos,
1433 ) -> Vec<NautilusWsMessage> {
1434 let mut result = Vec::new();
1435
1436 let coin = match data {
1437 WsActiveAssetCtxData::Perp { coin, .. } => coin,
1438 WsActiveAssetCtxData::Spot { coin, .. } => coin,
1439 };
1440
1441 if let Some(instrument) = instruments.get(coin) {
1442 let (mark_px, oracle_px, funding, open_interest) = match data {
1443 WsActiveAssetCtxData::Perp { ctx, .. } => (
1444 &ctx.shared.mark_px,
1445 Some(&ctx.oracle_px),
1446 Some(&ctx.funding),
1447 Some(&ctx.open_interest),
1448 ),
1449 WsActiveAssetCtxData::Spot { ctx, .. } => (&ctx.shared.mark_px, None, None, None),
1450 };
1451
1452 let mark_changed = asset_context_caches.mark_price.get(coin) != Some(mark_px);
1453 let index_changed =
1454 oracle_px.is_some_and(|px| asset_context_caches.index_price.get(coin) != Some(px));
1455 let funding_changed = funding
1456 .is_some_and(|rate| asset_context_caches.funding_rate.get(coin) != Some(rate));
1457 let open_interest_changed = open_interest
1458 .is_some_and(|value| asset_context_caches.open_interest.get(coin) != Some(value));
1459
1460 let subscribed_types = asset_context_subs.get(coin);
1461
1462 if mark_changed || index_changed || funding_changed {
1463 match parse_ws_asset_context(data, instrument, ts_init) {
1464 Ok((mark_price, index_price, funding_rate)) => {
1465 if mark_changed
1466 && subscribed_types
1467 .is_some_and(|s| s.contains(&AssetContextDataType::MarkPrice))
1468 {
1469 asset_context_caches.mark_price.insert(*coin, *mark_px);
1470 result.push(NautilusWsMessage::MarkPrice(mark_price));
1471 }
1472
1473 if index_changed
1474 && subscribed_types
1475 .is_some_and(|s| s.contains(&AssetContextDataType::IndexPrice))
1476 {
1477 if let Some(px) = oracle_px {
1478 asset_context_caches.index_price.insert(*coin, *px);
1479 }
1480
1481 if let Some(index) = index_price {
1482 result.push(NautilusWsMessage::IndexPrice(index));
1483 }
1484 }
1485
1486 if funding_changed
1487 && subscribed_types
1488 .is_some_and(|s| s.contains(&AssetContextDataType::FundingRate))
1489 {
1490 if let Some(rate) = funding {
1491 asset_context_caches.funding_rate.insert(*coin, *rate);
1492 }
1493
1494 if let Some(funding) = funding_rate {
1495 result.push(NautilusWsMessage::FundingRate(funding));
1496 }
1497 }
1498 }
1499 Err(e) => {
1500 log::error!("Error parsing asset context: {e}");
1501 }
1502 }
1503 }
1504
1505 if let Some(value) = open_interest
1506 && open_interest_changed
1507 && subscribed_types.is_some_and(|s| s.contains(&AssetContextDataType::OpenInterest))
1508 {
1509 match parse_ws_open_interest(*value, instrument, ts_init) {
1510 Ok(open_interest_data) => {
1511 asset_context_caches.open_interest.insert(*coin, *value);
1512
1513 let data_type =
1514 Self::open_interest_data_type(open_interest_data.instrument_id);
1515 result.push(NautilusWsMessage::CustomData(Data::Custom(
1516 CustomData::new(Arc::new(open_interest_data), data_type),
1517 )));
1518 }
1519 Err(e) => {
1520 log::error!("Error parsing open interest: {e}");
1521 }
1522 }
1523 }
1524 } else {
1525 log::debug!("No instrument found for coin: {coin}");
1526 }
1527
1528 result
1529 }
1530
1531 fn handle_all_dexs_asset_ctxs(
1532 data: WsAllDexsAssetCtxsData,
1533 all_dex_asset_ctxs_instrument_ids: &AHashMap<Ustr, Vec<Option<InstrumentId>>>,
1534 ts_init: UnixNanos,
1535 ) -> Option<NautilusWsMessage> {
1536 let mut entries = Vec::new();
1537
1538 for (dex, ctxs) in data.ctxs {
1539 let dex_key = Ustr::from(dex.as_str());
1540 let Some(instrument_ids) = all_dex_asset_ctxs_instrument_ids.get(&dex_key) else {
1541 log::warn!("Missing Hyperliquid allDexsAssetCtxs mapping for dex='{dex}'");
1542 continue;
1543 };
1544
1545 if ctxs.len() != instrument_ids.len() {
1546 log::warn!(
1550 "Hyperliquid allDexsAssetCtxs count mismatch for dex='{dex}': received {} contexts but cached {} instrument IDs (the next instrument refresh, instrument request, or data client connect rebuilds the mapping)",
1551 ctxs.len(),
1552 instrument_ids.len()
1553 );
1554 }
1555
1556 for (index, ctx) in ctxs.into_iter().enumerate() {
1557 let Some(Some(instrument_id)) = instrument_ids.get(index).copied() else {
1558 log::warn!(
1559 "Missing Hyperliquid allDexsAssetCtxs instrument mapping for dex='{dex}' index={index}"
1560 );
1561 continue;
1562 };
1563
1564 match Self::normalize_all_dex_asset_ctx_entry(&dex, instrument_id, ctx) {
1565 Ok(entry) => entries.push(entry),
1566 Err(e) => {
1567 log::warn!(
1568 "Failed to normalize Hyperliquid allDexsAssetCtxs entry dex='{dex}' index={index}: {e}"
1569 );
1570 }
1571 }
1572 }
1573 }
1574
1575 if entries.is_empty() {
1576 return None;
1577 }
1578
1579 let payload = HyperliquidAllDexsAssetCtxs::new(entries, ts_init, ts_init);
1580 let data_type = DataType::new("HyperliquidAllDexsAssetCtxs", None, None);
1581 Some(NautilusWsMessage::CustomData(Data::Custom(
1582 CustomData::new(Arc::new(payload), data_type),
1583 )))
1584 }
1585
1586 fn normalize_all_dex_asset_ctx_entry(
1587 dex: &str,
1588 instrument_id: InstrumentId,
1589 ctx: super::messages::PerpsAssetCtx,
1590 ) -> anyhow::Result<HyperliquidDexAssetCtx> {
1591 let mark_price = Price::from_decimal(ctx.shared.mark_px).map_err(anyhow::Error::msg)?;
1592 let oracle_price = Price::from_decimal(ctx.oracle_px).map_err(anyhow::Error::msg)?;
1593 let prev_day_price =
1594 Price::from_decimal(ctx.shared.prev_day_px).map_err(anyhow::Error::msg)?;
1595 let mid_price = ctx
1596 .shared
1597 .mid_px
1598 .map(|value| Price::from_decimal(value).map_err(anyhow::Error::msg))
1599 .transpose()?;
1600 let funding_rate = ctx.funding;
1601 let open_interest = ctx.open_interest;
1602 let premium = ctx.premium;
1603 let day_ntl_volume = ctx.shared.day_ntl_vlm;
1604 let day_base_volume = ctx
1605 .shared
1606 .day_base_vlm
1607 .ok_or_else(|| anyhow::anyhow!("missing dayBaseVlm"))?;
1608 let impact_prices = match ctx.shared.impact_pxs {
1609 Some(values) => match values.as_slice() {
1610 [bid, ask] => Some(HyperliquidImpactPrices {
1611 bid: Price::from_decimal(*bid).map_err(anyhow::Error::msg)?,
1612 ask: Price::from_decimal(*ask).map_err(anyhow::Error::msg)?,
1613 }),
1614 other => {
1615 anyhow::bail!("expected 2 impact prices, received {}", other.len());
1616 }
1617 },
1618 None => None,
1619 };
1620
1621 Ok(HyperliquidDexAssetCtx {
1622 dex: dex.to_string(),
1623 instrument_id,
1624 mark_price,
1625 oracle_price,
1626 prev_day_price,
1627 mid_price,
1628 impact_prices,
1629 funding_rate,
1630 open_interest,
1631 premium,
1632 day_ntl_volume,
1633 day_base_volume,
1634 })
1635 }
1636
1637 fn open_interest_data_type(instrument_id: InstrumentId) -> DataType {
1638 let metadata = Params::new(
1639 [(
1640 "instrument_id".to_string(),
1641 serde_json::Value::String(instrument_id.to_string()),
1642 )]
1643 .into(),
1644 );
1645 DataType::new(
1646 "HyperliquidOpenInterest",
1647 Some(metadata),
1648 Some(instrument_id.to_string()),
1649 )
1650 }
1651
1652 fn public_trade_data_type(instrument_id: InstrumentId) -> DataType {
1653 let metadata = Params::new(
1654 [(
1655 "instrument_id".to_string(),
1656 serde_json::Value::String(instrument_id.to_string()),
1657 )]
1658 .into(),
1659 );
1660 DataType::new(
1661 "HyperliquidPublicTrade",
1662 Some(metadata),
1663 Some(instrument_id.to_string()),
1664 )
1665 }
1666
1667 fn handle_user_twap_history(
1668 data: &super::messages::WsUserTwapHistoryData,
1669 context: FrameContext,
1670 instruments: &AHashMap<Ustr, InstrumentAny>,
1671 ts_init: UnixNanos,
1672 ) -> Vec<NautilusWsMessage> {
1673 let is_snapshot = data.is_snapshot.unwrap_or(false);
1674 let mut result = Vec::with_capacity(data.history.len());
1675
1676 for row in &data.history {
1677 let instrument = instruments.get(&row.state.coin);
1678 match parse_ws_twap_history_row(row, &data.user, is_snapshot, instrument, ts_init) {
1679 Ok(payload) => {
1680 let user = payload.user.clone();
1681 result.push(NautilusWsMessage::CustomData(Data::Custom(
1682 CustomData::new(Arc::new(payload), Self::twap_history_data_type(&user)),
1683 )));
1684 }
1685 Err(_) => {
1686 context.log_conversion_error("twap_history", log::Level::Error);
1687 }
1688 }
1689 }
1690
1691 result
1692 }
1693
1694 fn handle_user_twap_slice_fills(
1695 data: &super::messages::WsUserTwapSliceFillsData,
1696 context: FrameContext,
1697 instruments: &AHashMap<Ustr, InstrumentAny>,
1698 ts_init: UnixNanos,
1699 ) -> Vec<NautilusWsMessage> {
1700 let is_snapshot = data.is_snapshot.unwrap_or(false);
1701 let mut result = Vec::with_capacity(data.twap_slice_fills.len());
1702
1703 for item in &data.twap_slice_fills {
1704 let instrument = instruments.get(&item.fill.coin);
1705 match parse_ws_twap_slice_fill(item, &data.user, is_snapshot, instrument, ts_init) {
1706 Ok(payload) => {
1707 let user = payload.user.clone();
1708 result.push(NautilusWsMessage::CustomData(Data::Custom(
1709 CustomData::new(Arc::new(payload), Self::twap_slice_fill_data_type(&user)),
1710 )));
1711 }
1712 Err(_) => {
1713 context.log_conversion_error("twap_slice_fill", log::Level::Error);
1714 }
1715 }
1716 }
1717
1718 result
1719 }
1720
1721 fn twap_history_data_type(user: &str) -> DataType {
1722 let metadata = Params::new(
1723 [(
1724 "user".to_string(),
1725 serde_json::Value::String(user.to_string()),
1726 )]
1727 .into(),
1728 );
1729 DataType::new(
1730 "HyperliquidTwapHistory",
1731 Some(metadata),
1732 Some(user.to_string()),
1733 )
1734 }
1735
1736 fn twap_slice_fill_data_type(user: &str) -> DataType {
1737 let metadata = Params::new(
1738 [(
1739 "user".to_string(),
1740 serde_json::Value::String(user.to_string()),
1741 )]
1742 .into(),
1743 );
1744 DataType::new(
1745 "HyperliquidTwapSliceFill",
1746 Some(metadata),
1747 Some(user.to_string()),
1748 )
1749 }
1750}
1751
1752#[derive(Debug, Default)]
1753struct CompactBookStream {
1754 book: Option<CompactBook>,
1755 desired: bool,
1756 confirmed: bool,
1757 generation: u64,
1758 pending: VecDeque<(bool, u64)>,
1759 output_gate: SnapshotGate,
1760}
1761
1762impl Drop for CompactBookStream {
1763 fn drop(&mut self) {
1764 self.output_gate.lock().close();
1765 }
1766}
1767
1768#[derive(Clone, Copy)]
1769struct FrameContext {
1770 client_id: u64,
1771 payload_bytes: usize,
1772}
1773
1774impl FrameContext {
1775 fn log_decode_error(self, text: &str, e: &serde_json::Error) {
1776 let channel = serde_json::from_str::<FrameHeader>(text)
1778 .map_or("unknown", |header| header.channel.as_str());
1779
1780 log::error!(
1781 "Error parsing WebSocket message: channel={channel}, client_id={}, payload_bytes={}, category={:?}, line={}, column={}",
1782 self.client_id,
1783 self.payload_bytes,
1784 e.classify(),
1785 e.line(),
1786 e.column(),
1787 );
1788 }
1789
1790 fn log_conversion_error(self, class: &'static str, level: log::Level) {
1791 log::log!(
1792 level,
1793 "Error parsing WebSocket message: class={class}, client_id={}, payload_bytes={}, category=conversion",
1794 self.client_id,
1795 self.payload_bytes,
1796 );
1797 }
1798}
1799
1800#[derive(Deserialize)]
1801struct FrameHeader {
1802 channel: HyperliquidWsChannel,
1803}
1804
1805#[derive(Debug, thiserror::Error)]
1806enum PostSendError {
1807 #[error(transparent)]
1808 Transport(SendError),
1809 #[error(transparent)]
1810 Retry(RetryError),
1811 #[error("Post deadline expired")]
1812 Deadline,
1813}
1814
1815async fn send_post_with_retry<F, Fut>(
1816 retry_manager: &RetryManager<PostSendError>,
1817 deadline: tokio::time::Instant,
1818 cancellation_token: &CancellationToken,
1819 send: F,
1820) -> Result<(), PostSendError>
1821where
1822 F: Fn() -> Fut + Clone,
1823 Fut: Future<Output = Result<(), PostSendError>>,
1824{
1825 let invocation = retry_manager
1826 .invocation(
1827 "websocket_post_send",
1828 || {
1829 let send = send.clone();
1830 async move { send_post_before_deadline(deadline, cancellation_token, send).await }
1831 },
1832 should_retry_post_send,
1833 PostSendError::Retry,
1834 )
1835 .cancellation_token(cancellation_token)
1836 .execute();
1837 tokio::pin!(invocation);
1838
1839 tokio::select! {
1840 biased;
1841 () = tokio::time::sleep_until(deadline) => {
1842 Err(PostSendError::Deadline)
1843 }
1844 result = &mut invocation => result,
1845 }
1846}
1847
1848async fn send_post_before_deadline<F, Fut>(
1849 deadline: tokio::time::Instant,
1850 cancellation_token: &CancellationToken,
1851 send: F,
1852) -> Result<(), PostSendError>
1853where
1854 F: FnOnce() -> Fut,
1855 Fut: Future<Output = Result<(), PostSendError>>,
1856{
1857 if cancellation_token.is_cancelled() {
1858 return Err(PostSendError::Retry(RetryError::Canceled));
1859 }
1860
1861 if tokio::time::Instant::now() >= deadline {
1862 return Err(PostSendError::Deadline);
1863 }
1864
1865 send().await
1866}
1867
1868fn should_retry_post_send(error: &PostSendError) -> bool {
1869 matches!(
1870 error,
1871 PostSendError::Transport(SendError::Timeout | SendError::ConnectionChanged)
1872 )
1873}
1874
1875fn subscription_response_key(
1876 sub: &SubscriptionRequest,
1877 subscriptions: &SubscriptionState,
1878) -> String {
1879 let key = subscription_to_key(sub);
1880
1881 let SubscriptionRequest::SpotState { user, .. } = sub else {
1882 return key;
1883 };
1884
1885 let prefix = format!("{}:{user}:", HyperliquidWsChannel::SpotState.as_str());
1887 subscriptions
1888 .all_topics()
1889 .into_iter()
1890 .find(|topic| topic.starts_with(&prefix))
1891 .unwrap_or(key)
1892}
1893
1894pub(super) fn subscription_to_key(sub: &SubscriptionRequest) -> String {
1895 match sub {
1896 SubscriptionRequest::AllMids { dex } => {
1897 if let Some(dex_name) = dex {
1898 format!("{}:{dex_name}", HyperliquidWsChannel::AllMids.as_str())
1899 } else {
1900 HyperliquidWsChannel::AllMids.as_str().to_string()
1901 }
1902 }
1903 SubscriptionRequest::AllDexsAssetCtxs => {
1904 HyperliquidWsChannel::AllDexsAssetCtxs.as_str().to_string()
1905 }
1906 SubscriptionRequest::Notification { user } => {
1907 format!("{}:{user}", HyperliquidWsChannel::Notification.as_str())
1908 }
1909 SubscriptionRequest::WebData2 { user } => {
1910 format!("{}:{user}", HyperliquidWsChannel::WebData2.as_str())
1911 }
1912 SubscriptionRequest::ClearinghouseState { user } => {
1913 format!(
1914 "{}:{user}",
1915 HyperliquidWsChannel::ClearinghouseState.as_str()
1916 )
1917 }
1918 SubscriptionRequest::SpotState {
1919 user,
1920 is_portfolio_margin,
1921 } => {
1922 format!(
1923 "{}:{user}:{is_portfolio_margin}",
1924 HyperliquidWsChannel::SpotState.as_str()
1925 )
1926 }
1927 SubscriptionRequest::Candle { coin, interval } => {
1928 format!(
1929 "{}:{coin}:{}",
1930 HyperliquidWsChannel::Candle.as_str(),
1931 interval.as_str()
1932 )
1933 }
1934 SubscriptionRequest::L2Book { coin, .. } => {
1935 format!("{}:{coin}", HyperliquidWsChannel::L2Book.as_str())
1936 }
1937 SubscriptionRequest::L2 { coin, .. } => {
1938 format!("{}:{coin}", HyperliquidWsChannel::L2.as_str())
1939 }
1940 SubscriptionRequest::Trades { coin } => {
1941 format!("{}:{coin}", HyperliquidWsChannel::Trades.as_str())
1942 }
1943 SubscriptionRequest::OrderUpdates { user } => {
1944 format!("{}:{user}", HyperliquidWsChannel::OrderUpdates.as_str())
1945 }
1946 SubscriptionRequest::UserEvents { user } => {
1947 format!("{}:{user}", HyperliquidWsChannel::UserEvents.as_str())
1948 }
1949 SubscriptionRequest::UserFills { user, .. } => {
1950 format!("{}:{user}", HyperliquidWsChannel::UserFills.as_str())
1951 }
1952 SubscriptionRequest::UserFundings { user } => {
1953 format!("{}:{user}", HyperliquidWsChannel::UserFundings.as_str())
1954 }
1955 SubscriptionRequest::UserNonFundingLedgerUpdates { user } => {
1956 format!(
1957 "{}:{user}",
1958 HyperliquidWsChannel::UserNonFundingLedgerUpdates.as_str()
1959 )
1960 }
1961 SubscriptionRequest::ActiveAssetCtx { coin } => {
1962 format!("{}:{coin}", HyperliquidWsChannel::ActiveAssetCtx.as_str())
1963 }
1964 SubscriptionRequest::ActiveSpotAssetCtx { coin } => {
1965 format!(
1966 "{}:{coin}",
1967 HyperliquidWsChannel::ActiveSpotAssetCtx.as_str()
1968 )
1969 }
1970 SubscriptionRequest::ActiveAssetData { user, coin } => {
1971 format!(
1972 "{}:{user}:{coin}",
1973 HyperliquidWsChannel::ActiveAssetData.as_str()
1974 )
1975 }
1976 SubscriptionRequest::UserTwapSliceFills { user } => {
1977 format!(
1978 "{}:{user}",
1979 HyperliquidWsChannel::UserTwapSliceFills.as_str()
1980 )
1981 }
1982 SubscriptionRequest::UserTwapHistory { user } => {
1983 format!("{}:{user}", HyperliquidWsChannel::UserTwapHistory.as_str())
1984 }
1985 SubscriptionRequest::Bbo { coin } => {
1986 format!("{}:{coin}", HyperliquidWsChannel::Bbo.as_str())
1987 }
1988 }
1989}
1990
1991pub(crate) fn should_retry_hyperliquid_error(error: &HyperliquidWsError) -> bool {
1993 match error {
1994 HyperliquidWsError::TungsteniteError(_) => true,
1995 HyperliquidWsError::ClientError(msg) => {
1996 let msg_lower = msg.to_lowercase();
1997 msg_lower.contains("timeout")
1998 || msg_lower.contains("timed out")
1999 || msg_lower.contains("connection")
2000 || msg_lower.contains("network")
2001 }
2002 _ => false,
2003 }
2004}
2005
2006fn serialize_request(request: &HyperliquidWsRequest) -> Result<String, HyperliquidWsError> {
2007 serde_json::to_string(request)
2008 .map_err(|e| HyperliquidWsError::MessageSerialization(e.to_string()))
2009}
2010
2011pub(crate) fn create_hyperliquid_timeout_error(msg: String) -> HyperliquidWsError {
2013 HyperliquidWsError::ClientError(msg)
2014}
2015
2016#[cfg(test)]
2017pub(super) mod tests {
2018 use std::{
2019 sync::{
2020 Arc, Once,
2021 atomic::{AtomicBool, AtomicUsize, Ordering},
2022 },
2023 time::Duration,
2024 };
2025
2026 use ahash::{AHashMap, AHashSet};
2027 use log::{Level, LevelFilter, Log, Metadata, Record};
2028 use nautilus_common::cache::fifo::FifoCacheMap;
2029 use nautilus_core::nanos::UnixNanos;
2030 use nautilus_live::book::snapshot::SnapshotGate;
2031 use nautilus_model::{
2032 data::Data,
2033 identifiers::{ClientOrderId, InstrumentId, Symbol},
2034 instruments::{CryptoPerpetual, Instrument, InstrumentAny},
2035 types::{Currency, Price, Quantity},
2036 };
2037 use nautilus_network::{
2038 error::SendError,
2039 retry::{RetryConfig, RetryError, RetryManager},
2040 websocket::SubscriptionState,
2041 };
2042 use parking_lot::Mutex;
2043 use rstest::rstest;
2044 use rust_decimal::Decimal;
2045 use rust_decimal_macros::dec;
2046 use serde_json::json;
2047 use tokio_tungstenite::tungstenite::Message;
2048 use tokio_util::sync::CancellationToken;
2049 use ustr::Ustr;
2050
2051 use super::{
2052 super::{
2053 client::{AssetContextDataType, CLOID_CACHE_CAPACITY, CloidCache},
2054 error::HyperliquidWsError,
2055 messages::{
2056 HyperliquidWsRequest, NautilusWsMessage, PerpsAssetCtx, PostRequest,
2057 SharedAssetCtx, SpotAssetCtx, SubscriptionRequest, WsActiveAssetCtxData,
2058 WsAllDexsAssetCtxsData, WsBookData, WsLevelData,
2059 },
2060 post::PostRouter,
2061 rate_limits::WebSocketRateLimits,
2062 },
2063 AllMidsDataTypeCache, AssetContextCaches, FeedHandler, HandlerCommand, PostSendError,
2064 send_post_before_deadline, send_post_with_retry, should_retry_post_send,
2065 };
2066 use crate::{
2067 common::consts::{
2068 HYPERLIQUID_VENUE, HYPERLIQUID_WS_MESSAGES_PER_MINUTE, HYPERLIQUID_WS_SUBSCRIPTIONS_MAX,
2069 },
2070 data_types::{HyperliquidAllDexsAssetCtxs, HyperliquidOpenInterest},
2071 };
2072
2073 const SECRET_MARKER: &str = "OUTBOUND_SECRET_MARKER";
2074
2075 struct LogCapture {
2076 messages: Mutex<Vec<String>>,
2077 }
2078
2079 static LOG_CAPTURE: LogCapture = LogCapture {
2080 messages: Mutex::new(Vec::new()),
2081 };
2082
2083 static LOG_INSTALL: Once = Once::new();
2084 static LOG_LOCK: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
2085
2086 impl LogCapture {
2087 fn clear(&self) {
2088 self.messages.lock().clear();
2089 }
2090
2091 fn messages(&self) -> Vec<String> {
2092 self.messages.lock().clone()
2093 }
2094 }
2095
2096 impl Log for LogCapture {
2097 fn enabled(&self, metadata: &Metadata<'_>) -> bool {
2098 metadata.level() <= Level::Debug
2099 && metadata.target().starts_with("nautilus_hyperliquid::")
2100 }
2101
2102 fn log(&self, record: &Record<'_>) {
2103 if self.enabled(record.metadata()) {
2104 let message = record.args().to_string();
2105 self.messages.lock().push(message);
2106 }
2107 }
2108
2109 fn flush(&self) {}
2110 }
2111
2112 #[rstest]
2113 fn all_mids_cache_projects_subscriptions_without_scanning_every_websocket_message() {
2114 let mut cache = AllMidsDataTypeCache::default();
2115
2116 assert_eq!(cache.as_slice().len(), 1);
2117 assert!(cache.as_slice()[0].metadata().is_none());
2118
2119 cache.apply(
2120 &SubscriptionRequest::AllMids {
2121 dex: Some("xyz".to_owned()),
2122 },
2123 true,
2124 );
2125 assert_eq!(cache.as_slice().len(), 1);
2126 assert_eq!(
2127 cache.as_slice()[0]
2128 .metadata()
2129 .and_then(|metadata| metadata.get_str("dex")),
2130 Some("xyz"),
2131 );
2132
2133 cache.apply(&SubscriptionRequest::AllMids { dex: None }, true);
2134 assert_eq!(cache.as_slice().len(), 2);
2135
2136 cache.apply(
2137 &SubscriptionRequest::AllMids {
2138 dex: Some("xyz".to_owned()),
2139 },
2140 false,
2141 );
2142 assert_eq!(cache.as_slice().len(), 1);
2143 assert_eq!(cache.as_slice()[0].type_name(), "HyperliquidAllMids");
2144 assert!(cache.as_slice()[0].metadata().is_none());
2145
2146 cache.apply(&SubscriptionRequest::AllMids { dex: None }, false);
2147 assert_eq!(cache.as_slice().len(), 1);
2148 assert_eq!(cache.as_slice()[0].type_name(), "HyperliquidAllMids");
2149 assert!(cache.as_slice()[0].metadata().is_none());
2150 }
2151
2152 fn btc_perp() -> InstrumentAny {
2153 InstrumentAny::CryptoPerpetual(
2154 CryptoPerpetual::builder()
2155 .instrument_id(InstrumentId::new(
2156 Symbol::new("BTC-PERP"),
2157 *HYPERLIQUID_VENUE,
2158 ))
2159 .raw_symbol(Symbol::new("BTC-PERP"))
2160 .base_currency(Currency::from("BTC"))
2161 .quote_currency(Currency::from("USDC"))
2162 .settlement_currency(Currency::from("USDC"))
2163 .is_inverse(false)
2164 .price_precision(2)
2165 .size_precision(3)
2166 .price_increment(Price::from("0.01"))
2167 .size_increment(Quantity::from("0.001"))
2168 .ts_event(UnixNanos::default())
2169 .ts_init(UnixNanos::default())
2170 .build()
2171 .unwrap(),
2172 )
2173 }
2174
2175 fn one_level_book() -> WsBookData {
2176 WsBookData {
2177 coin: Ustr::from("BTC"),
2178 levels: [
2179 vec![WsLevelData {
2180 px: dec!(100.00),
2181 sz: dec!(1.0),
2182 n: 1,
2183 }],
2184 vec![WsLevelData {
2185 px: dec!(100.01),
2186 sz: dec!(1.0),
2187 n: 1,
2188 }],
2189 ],
2190 time: 1_700_000_000_000,
2191 }
2192 }
2193
2194 fn compact_handler() -> FeedHandler {
2195 let (_, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
2196 let (_, raw_rx) = tokio::sync::mpsc::unbounded_channel();
2197 let (out_tx, _) = tokio::sync::mpsc::unbounded_channel();
2198 let mut handler = FeedHandler::new(
2199 Arc::new(AtomicBool::new(false)),
2200 cmd_rx,
2201 raw_rx,
2202 out_tx,
2203 None,
2204 SubscriptionState::new(':'),
2205 Arc::new(Mutex::new(FifoCacheMap::new())),
2206 PostRouter::new(),
2207 Arc::new(WebSocketRateLimits::new()),
2208 1,
2209 );
2210 handler.instruments.insert(Ustr::from("BTC"), btc_perp());
2211 handler
2212 }
2213
2214 #[rstest]
2215 #[tokio::test]
2216 async fn compact_replacement_waits_for_current_ack_and_new_baseline() {
2217 use super::super::messages::{WsCompactBookData, WsCompactBookUpdate};
2218
2219 let mut handler = compact_handler();
2220 let sub = SubscriptionRequest::L2 {
2221 coin: "BTC".into(),
2222 n_sig_figs: Some(5),
2223 mantissa: Some(2),
2224 };
2225 let subscribe = HyperliquidWsRequest::Subscribe {
2226 subscription: sub.clone(),
2227 };
2228 let unsubscribe = HyperliquidWsRequest::Unsubscribe {
2229 subscription: sub.clone(),
2230 };
2231 handler.subscriptions.mark_subscribe("l2:BTC");
2232 handler.prepare_compact_request(&subscribe);
2233 handler.prepare_compact_request(&unsubscribe);
2234 handler.prepare_compact_request(&subscribe);
2235
2236 handler.confirm_compact_request(&sub, "subscribe");
2238 assert!(
2239 handler
2240 .handle_compact_book(
2241 WsCompactBookData::Snapshot(one_level_book()),
2242 UnixNanos::default()
2243 )
2244 .is_none()
2245 );
2246 handler.confirm_compact_request(&sub, "unsubscribe");
2247 handler.confirm_compact_request(&sub, "subscribe");
2248 let update: WsCompactBookUpdate = serde_json::from_value(json!({
2249 "c":"BTC","t":1700000000000_u64,"r":[[],[]],
2250 "l":[[{"p":"100","s":"2"}],[]],
2251 }))
2252 .unwrap();
2253 assert!(
2254 handler
2255 .handle_compact_book(
2256 WsCompactBookData::Update(update.clone()),
2257 UnixNanos::default()
2258 )
2259 .is_none()
2260 );
2261 let snapshot = handler.handle_compact_book(
2262 WsCompactBookData::Snapshot(one_level_book()),
2263 UnixNanos::default(),
2264 );
2265 assert!(
2266 matches!(&snapshot, Some(NautilusWsMessage::CompactBook { is_snapshot: true, deltas, .. }) if deltas.deltas.len() == 3)
2267 );
2268 let updated =
2269 handler.handle_compact_book(WsCompactBookData::Update(update), UnixNanos::default());
2270 assert!(
2271 matches!(&updated, Some(NautilusWsMessage::CompactBook { is_snapshot: false, deltas, .. }) if deltas.deltas[1].order.size == Quantity::from("2"))
2272 );
2273
2274 handler.prepare_compact_request(&unsubscribe);
2275 assert!(
2276 handler
2277 .handle_compact_book(
2278 WsCompactBookData::Snapshot(one_level_book()),
2279 UnixNanos::default()
2280 )
2281 .is_none()
2282 );
2283 handler.confirm_compact_request(&sub, "unsubscribe");
2284 assert!(!handler.compact_books.contains_key(&Ustr::from("BTC")));
2285 }
2286
2287 #[rstest]
2288 #[case::replacement(false)]
2289 #[case::reconnect(true)]
2290 #[tokio::test]
2291 async fn compact_replacement_retires_already_queued_snapshot(#[case] reconnect: bool) {
2292 use nautilus_common::live::dst::time::Instant;
2293
2294 use super::super::messages::WsCompactBookData;
2295 use crate::book::sync::BookSyncTracker;
2296
2297 let mut handler = compact_handler();
2298 let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel();
2299 handler.out_tx = tx;
2300 let sub = SubscriptionRequest::L2 {
2301 coin: "BTC".into(),
2302 n_sig_figs: None,
2303 mantissa: None,
2304 };
2305 let subscribe = HyperliquidWsRequest::Subscribe {
2306 subscription: sub.clone(),
2307 };
2308 handler.subscriptions.mark_subscribe("l2:BTC");
2309 handler.prepare_compact_request(&subscribe);
2310 handler.confirm_compact_request(&sub, "subscribe");
2311 let old = handler
2312 .handle_compact_book(
2313 WsCompactBookData::Snapshot(one_level_book()),
2314 UnixNanos::default(),
2315 )
2316 .unwrap();
2317 handler.send(old).unwrap();
2318 let invalid = serde_json::from_value(json!({
2319 "c":"BTC","t":1700000000001_u64,"r":[[9],[]],"l":[[],[]],
2320 }))
2321 .unwrap();
2322 let error = handler
2323 .handle_compact_book(WsCompactBookData::Update(invalid), UnixNanos::default())
2324 .unwrap();
2325 handler.send(error).unwrap();
2326
2327 let tracker = BookSyncTracker::default();
2329 let id = btc_perp().id();
2330 let stream_use = crate::websocket::book::BookStreamUse::Deltas;
2331 let registration = crate::websocket::book::BookStreamRegistry::default().register(
2332 "BTC".into(),
2333 stream_use,
2334 Default::default(),
2335 );
2336 let (cancel, gate) = tracker
2337 .register_compact(
2338 id,
2339 stream_use,
2340 registration,
2341 CancellationToken::new(),
2342 Instant::now(),
2343 |cancel, gate| Ok((cancel, gate)),
2344 )
2345 .unwrap()
2346 .unwrap();
2347
2348 if reconnect {
2349 handler.compact_books.clear();
2350 } else {
2351 handler.prepare_compact_request(&HyperliquidWsRequest::Unsubscribe {
2352 subscription: sub.clone(),
2353 });
2354 }
2355
2356 handler.prepare_compact_request(&subscribe);
2357 gate.open();
2358 let NautilusWsMessage::CompactBook { output_gate, .. } = rx.recv().await.unwrap() else {
2359 panic!("expected compact book");
2360 };
2361 assert!(output_gate.lock().is_closed());
2362 let NautilusWsMessage::BookInvalid {
2363 output_gate: Some(error_gate),
2364 ..
2365 } = rx.recv().await.unwrap()
2366 else {
2367 panic!("expected compact conversion error");
2368 };
2369 assert!(error_gate.lock().is_closed());
2370 assert!(!cancel.is_cancelled());
2371
2372 handler.confirm_compact_request(&sub, "unsubscribe");
2373 handler.confirm_compact_request(&sub, "subscribe");
2374 let fresh = handler
2375 .handle_compact_book(
2376 WsCompactBookData::Snapshot(one_level_book()),
2377 UnixNanos::default(),
2378 )
2379 .unwrap();
2380 let NautilusWsMessage::CompactBook {
2381 is_snapshot,
2382 output_gate,
2383 ..
2384 } = fresh
2385 else {
2386 panic!("expected replacement snapshot");
2387 };
2388 assert!(!output_gate.lock().is_closed());
2389 let mut published = false;
2390 tracker.record_compact(id, is_snapshot, Instant::now(), |deltas, _| {
2391 published = deltas;
2392 });
2393 assert!(published);
2394 assert!(cancel.is_cancelled());
2395 }
2396
2397 fn btc_active_spot_asset_ctx() -> WsActiveAssetCtxData {
2398 WsActiveAssetCtxData::Spot {
2399 coin: Ustr::from("BTC"),
2400 ctx: SpotAssetCtx {
2401 shared: SharedAssetCtx {
2402 day_ntl_vlm: dec!(1000000.0),
2403 prev_day_px: dec!(49000.0),
2404 mark_px: dec!(50000.0),
2405 mid_px: Some(dec!(50001.0)),
2406 impact_pxs: None,
2407 day_base_vlm: Some(dec!(100.0)),
2408 },
2409 circulating_supply: dec!(19000000.0),
2410 },
2411 }
2412 }
2413
2414 fn btc_active_asset_ctx(open_interest: Decimal) -> WsActiveAssetCtxData {
2415 WsActiveAssetCtxData::Perp {
2416 coin: Ustr::from("BTC"),
2417 ctx: PerpsAssetCtx {
2418 shared: SharedAssetCtx {
2419 day_ntl_vlm: dec!(1000000.0),
2420 prev_day_px: dec!(49000.0),
2421 mark_px: dec!(50000.0),
2422 mid_px: Some(dec!(50001.0)),
2423 impact_pxs: Some(vec![dec!(50000.0), dec!(50002.0)]),
2424 day_base_vlm: Some(dec!(100.0)),
2425 },
2426 funding: dec!(0.0001),
2427 open_interest,
2428 oracle_px: dec!(50005.0),
2429 premium: Some(dec!(-0.0001)),
2430 },
2431 }
2432 }
2433
2434 fn sample_all_dexs_asset_ctxs() -> WsAllDexsAssetCtxsData {
2435 let raw = include_str!("../../test_data/ws_all_dexs_asset_ctxs.json");
2436 let msg: super::super::messages::HyperliquidWsMessage =
2437 serde_json::from_str(raw).expect("expected valid allDexsAssetCtxs fixture");
2438
2439 let super::super::messages::HyperliquidWsMessage::AllDexsAssetCtxs { data } = msg else {
2440 panic!("expected allDexsAssetCtxs fixture message");
2441 };
2442
2443 let default_entry = data
2444 .ctxs
2445 .iter()
2446 .find(|(dex, _)| dex.is_empty())
2447 .and_then(|(dex, ctxs)| ctxs.first().cloned().map(|ctx| (dex.clone(), vec![ctx])))
2448 .expect("expected default dex sample");
2449 let xyz_entry = data
2450 .ctxs
2451 .iter()
2452 .find(|(dex, _)| dex == "xyz")
2453 .and_then(|(dex, ctxs)| ctxs.first().cloned().map(|ctx| (dex.clone(), vec![ctx])))
2454 .expect("expected xyz dex sample");
2455
2456 WsAllDexsAssetCtxsData {
2457 ctxs: vec![default_entry, xyz_entry],
2458 }
2459 }
2460
2461 #[tokio::test]
2462 async fn post_send_failure_cancels_router_waiter() {
2463 let signal = Arc::new(AtomicBool::new(false));
2464 let (cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
2465 let (raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
2466 let (out_tx, _out_rx) = tokio::sync::mpsc::unbounded_channel();
2467 let post_router = PostRouter::new();
2468 let cloid_cache: CloidCache = Arc::new(Mutex::new(FifoCacheMap::<
2469 Ustr,
2470 ClientOrderId,
2471 CLOID_CACHE_CAPACITY,
2472 >::new()));
2473 let mut handler = FeedHandler::new(
2474 signal,
2475 cmd_rx,
2476 raw_rx,
2477 out_tx,
2478 None,
2479 SubscriptionState::new(':'),
2480 cloid_cache,
2481 Arc::clone(&post_router),
2482 Arc::new(WebSocketRateLimits::new()),
2483 1,
2484 );
2485
2486 let id = 99;
2487 let cancellation_token = CancellationToken::new();
2488 let rx = post_router
2489 .register_with_cancellation(id, &cancellation_token)
2490 .await
2491 .unwrap();
2492
2493 let task = tokio::spawn(async move { handler.next().await });
2494
2495 cmd_tx
2496 .send(HandlerCommand::Post {
2497 id,
2498 request: PostRequest::Info {
2499 payload: json!({"type": "userRateLimit", "user": "0x123"}),
2500 },
2501 deadline: tokio::time::Instant::now() + Duration::from_secs(1),
2502 cancellation_token,
2503 })
2504 .unwrap();
2505 drop(cmd_tx);
2506 drop(raw_tx);
2507
2508 let closed = tokio::time::timeout(Duration::from_millis(100), rx)
2509 .await
2510 .expect("post waiter should close without waiting for post timeout");
2511 assert!(closed.is_err(), "post router cancel must close the waiter");
2512 let _rx = post_router
2513 .register(id)
2514 .await
2515 .expect("post id should be reusable after cancellation");
2516 assert!(task.await.unwrap().is_none());
2517 }
2518
2519 #[rstest]
2520 #[tokio::test]
2521 async fn write_book_opens_gate_only_after_completed_write() {
2522 let (cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
2523 let (raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
2524 let (out_tx, _out_rx) = tokio::sync::mpsc::unbounded_channel();
2525
2526 let cloid_cache: CloidCache = Arc::new(Mutex::new(FifoCacheMap::<
2527 Ustr,
2528 ClientOrderId,
2529 CLOID_CACHE_CAPACITY,
2530 >::new()));
2531
2532 let mut handler = FeedHandler::new(
2533 Arc::new(AtomicBool::new(false)),
2534 cmd_rx,
2535 raw_rx,
2536 out_tx,
2537 None,
2538 SubscriptionState::new(':'),
2539 cloid_cache,
2540 PostRouter::new(),
2541 Arc::new(WebSocketRateLimits::new()),
2542 1,
2543 );
2544
2545 let subscription = || SubscriptionRequest::L2Book {
2546 coin: Ustr::from("BTC"),
2547 n_sig_figs: None,
2548 mantissa: None,
2549 };
2550
2551 let failed_gate = SnapshotGate::default();
2552 failed_gate.lock().close();
2553 let (failed_tx, failed_rx) = tokio::sync::oneshot::channel();
2554 let cancelled_gate = SnapshotGate::default();
2555 cancelled_gate.lock().close();
2556 let cancelled = CancellationToken::new();
2557 cancelled.cancel();
2558 let (cancelled_tx, cancelled_rx) = tokio::sync::oneshot::channel();
2559
2560 cmd_tx
2562 .send(HandlerCommand::WriteBook {
2563 subscription: subscription(),
2564 replace: false,
2565 cancel: CancellationToken::new(),
2566 gate: failed_gate.clone(),
2567 completion: failed_tx,
2568 })
2569 .unwrap();
2570
2571 cmd_tx
2572 .send(HandlerCommand::WriteBook {
2573 subscription: subscription(),
2574 replace: true,
2575 cancel: cancelled,
2576 gate: cancelled_gate.clone(),
2577 completion: cancelled_tx,
2578 })
2579 .unwrap();
2580
2581 drop(cmd_tx);
2582 drop(raw_tx);
2583
2584 let next = handler.next().await;
2585 let failed = failed_rx.await.unwrap();
2586 let attempted = cancelled_rx.await.unwrap();
2587
2588 assert!(next.is_none());
2589 assert!(matches!(
2590 failed,
2591 Err(HyperliquidWsError::ClientError(message))
2592 if message == "No WebSocket client available"
2593 ));
2594 assert!(failed_gate.lock().is_closed());
2595 assert!(
2596 matches!(
2597 attempted,
2598 Err(HyperliquidWsError::ClientError(message))
2599 if message == "No WebSocket client available"
2600 ),
2601 "a cancelled write still runs",
2602 );
2603 assert!(cancelled_gate.lock().is_closed());
2604 }
2605
2606 fn retry_manager_with_backoff() -> RetryManager<PostSendError> {
2607 RetryManager::new(RetryConfig {
2608 max_retries: 1,
2609 initial_delay_ms: 1_000,
2610 max_delay_ms: 1_000,
2611 backoff_factor: 1.0,
2612 jitter_ms: 0,
2613 operation_timeout_ms: None,
2614 immediate_first: false,
2615 max_elapsed_ms: None,
2616 })
2617 }
2618
2619 #[rstest]
2620 #[tokio::test(start_paused = true)]
2621 async fn expired_post_deadline_prevents_first_send() {
2622 let cancellation_token = CancellationToken::new();
2623 let sends = Arc::new(AtomicUsize::new(0));
2624 let send_count = Arc::clone(&sends);
2625
2626 let error = send_post_before_deadline(
2627 tokio::time::Instant::now(),
2628 &cancellation_token,
2629 move || {
2630 let send_count = Arc::clone(&send_count);
2631 async move {
2632 send_count.fetch_add(1, Ordering::SeqCst);
2633 Ok(())
2634 }
2635 },
2636 )
2637 .await
2638 .unwrap_err();
2639
2640 assert!(matches!(error, PostSendError::Deadline));
2641 assert_eq!(sends.load(Ordering::SeqCst), 0);
2642 }
2643
2644 #[rstest]
2645 #[tokio::test(start_paused = true)]
2646 async fn post_deadline_while_waiting_for_message_quota_prevents_send() {
2647 let manager = retry_manager_with_backoff();
2648 let cancellation_token = CancellationToken::new();
2649 let limits = Arc::new(WebSocketRateLimits::new());
2650 let rate_key = limits.message_key();
2651 for _ in 0..HYPERLIQUID_WS_MESSAGES_PER_MINUTE {
2652 assert!(limits.messages.check_key(&rate_key).is_ok());
2653 }
2654 let sends = Arc::new(AtomicUsize::new(0));
2655 let send_count = Arc::clone(&sends);
2656 let send_limits = Arc::clone(&limits);
2657 let deadline = tokio::time::Instant::now() + Duration::from_millis(10);
2658
2659 let error = send_post_with_retry(&manager, deadline, &cancellation_token, move || {
2660 let send_count = Arc::clone(&send_count);
2661 let send_limits = Arc::clone(&send_limits);
2662 async move {
2663 send_limits.acquire_message().await;
2664 send_count.fetch_add(1, Ordering::SeqCst);
2665 Ok(())
2666 }
2667 })
2668 .await
2669 .unwrap_err();
2670
2671 assert!(matches!(error, PostSendError::Deadline));
2672 assert_eq!(sends.load(Ordering::SeqCst), 0);
2673 }
2674
2675 #[rstest]
2676 #[tokio::test(start_paused = true)]
2677 async fn post_deadline_during_backoff_prevents_retry() {
2678 let manager = retry_manager_with_backoff();
2679 let cancellation_token = CancellationToken::new();
2680 let sends = Arc::new(AtomicUsize::new(0));
2681 let send_count = Arc::clone(&sends);
2682 let deadline = tokio::time::Instant::now() + Duration::from_millis(100);
2683
2684 let error = send_post_with_retry(&manager, deadline, &cancellation_token, move || {
2685 let send_count = Arc::clone(&send_count);
2686 async move {
2687 send_count.fetch_add(1, Ordering::SeqCst);
2688 Err(PostSendError::Transport(SendError::Timeout))
2689 }
2690 })
2691 .await
2692 .unwrap_err();
2693
2694 assert!(matches!(error, PostSendError::Deadline));
2695 assert_eq!(sends.load(Ordering::SeqCst), 1);
2696 }
2697
2698 #[rstest]
2699 #[tokio::test(start_paused = true)]
2700 async fn post_deadline_after_send_starts_preserves_unknown_outcome() {
2701 let manager = retry_manager_with_backoff();
2702 let cancellation_token = CancellationToken::new();
2703 let sends = Arc::new(AtomicUsize::new(0));
2704 let send_count = Arc::clone(&sends);
2705 let deadline = tokio::time::Instant::now() + Duration::from_millis(100);
2706
2707 let error = send_post_with_retry(&manager, deadline, &cancellation_token, move || {
2708 let send_count = Arc::clone(&send_count);
2709 async move {
2710 send_count.fetch_add(1, Ordering::SeqCst);
2711 std::future::pending::<Result<(), PostSendError>>().await
2712 }
2713 })
2714 .await
2715 .unwrap_err();
2716
2717 assert!(matches!(error, PostSendError::Deadline));
2718 assert_eq!(sends.load(Ordering::SeqCst), 1);
2719 }
2720
2721 #[rstest]
2722 #[tokio::test(start_paused = true)]
2723 async fn post_cancellation_stops_started_send() {
2724 let manager = retry_manager_with_backoff();
2725 let cancellation_token = CancellationToken::new();
2726 let task_cancellation_token = cancellation_token.clone();
2727 let started = Arc::new(tokio::sync::Notify::new());
2728 let task_started = Arc::clone(&started);
2729 let sends = Arc::new(AtomicUsize::new(0));
2730 let task_sends = Arc::clone(&sends);
2731 let deadline = tokio::time::Instant::now() + Duration::from_secs(60);
2732 let task = tokio::spawn(async move {
2733 send_post_with_retry(&manager, deadline, &task_cancellation_token, move || {
2734 let task_started = Arc::clone(&task_started);
2735 let task_sends = Arc::clone(&task_sends);
2736 async move {
2737 task_sends.fetch_add(1, Ordering::SeqCst);
2738 task_started.notify_one();
2739 std::future::pending::<Result<(), PostSendError>>().await
2740 }
2741 })
2742 .await
2743 });
2744
2745 started.notified().await;
2746 cancellation_token.cancel();
2747 let error = task.await.unwrap().unwrap_err();
2748
2749 assert!(matches!(error, PostSendError::Retry(RetryError::Canceled)));
2750 assert_eq!(sends.load(Ordering::SeqCst), 1);
2751 }
2752
2753 #[rstest]
2754 #[case(SendError::Timeout, true)]
2755 #[case(SendError::ConnectionChanged, true)]
2756 #[case(SendError::WriteTimeout, false)]
2757 #[case(SendError::BrokenPipe("transport failed".to_string()), false)]
2758 #[case(SendError::Closed, false)]
2759 #[case(SendError::InvalidInput("invalid payload".to_string()), false)]
2760 fn post_send_retries_only_before_writing(#[case] error: SendError, #[case] expected: bool) {
2761 assert_eq!(
2762 should_retry_post_send(&PostSendError::Transport(error)),
2763 expected
2764 );
2765 }
2766
2767 #[tokio::test]
2768 async fn malformed_private_frame_logs_omit_payloads() {
2769 let _capture = capture_logs().await;
2770
2771 let fixtures: serde_json::Value = serde_json::from_str(include_str!(
2772 "../../test_data/ws_malformed_private_frames.json"
2773 ))
2774 .unwrap();
2775 let signal = Arc::new(AtomicBool::new(false));
2776 let (cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
2777 let (raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
2778 let (out_tx, _out_rx) = tokio::sync::mpsc::unbounded_channel();
2779 let cloid_cache: CloidCache = Arc::new(Mutex::new(FifoCacheMap::new()));
2780
2781 let mut handler = FeedHandler::new(
2782 signal,
2783 cmd_rx,
2784 raw_rx,
2785 out_tx,
2786 Some("HYPERLIQUID-PRIVATE_ACCOUNT_SENTINEL".into()),
2787 SubscriptionState::new(':'),
2788 cloid_cache,
2789 PostRouter::new(),
2790 Arc::new(WebSocketRateLimits::new()),
2791 937,
2792 );
2793 let instrument = btc_perp();
2794 handler.instruments.insert(Ustr::from("BTC"), instrument);
2795 let mut expected = Vec::new();
2796
2797 for case in fixtures["decode"].as_array().unwrap() {
2798 let text = case["text"].as_str().unwrap();
2799 let e = super::super::messages::decode_ws_message(text).unwrap_err();
2800 let channel = case["channel"].as_str().unwrap();
2801 expected.push(format!(
2802 "Error parsing WebSocket message: channel={channel}, client_id=937, payload_bytes={}, category={:?}, line={}, column={}",
2803 text.len(), e.classify(), e.line(), e.column(),
2804 ));
2805 raw_tx.send(Message::Text(text.to_owned().into())).unwrap();
2806 }
2807
2808 for case in fixtures["conversion"].as_array().unwrap() {
2809 let text = case["message"].to_string();
2810 super::super::messages::decode_ws_message(&text).unwrap();
2811 let class = case["class"].as_str().unwrap();
2812 expected.push(format!(
2813 "Error parsing WebSocket message: class={class}, client_id=937, payload_bytes={}, category=conversion",
2814 text.len(),
2815 ));
2816 raw_tx.send(Message::Text(text.into())).unwrap();
2817 }
2818
2819 raw_tx
2820 .send(Message::Text(nautilus_network::RECONNECTED.into()))
2821 .unwrap();
2822 drop(raw_tx);
2823 drop(cmd_tx);
2824
2825 let next = tokio::time::timeout(Duration::from_secs(5), handler.next())
2826 .await
2827 .unwrap();
2828 let messages = LOG_CAPTURE.messages();
2829
2830 let errors: Vec<_> = messages
2831 .iter()
2832 .filter(|message| {
2833 message.starts_with("Error parsing WebSocket message:")
2834 && message.contains("client_id=937,")
2835 })
2836 .cloned()
2837 .collect();
2838
2839 assert!(matches!(next, Some(NautilusWsMessage::Reconnected)));
2840 assert_eq!(errors, expected);
2841
2842 for secret in fixtures["secrets"].as_array().unwrap() {
2843 let secret = secret.as_str().unwrap();
2844 assert!(
2845 messages.iter().all(|message| !message.contains(secret)),
2846 "private value leaked: {secret}"
2847 );
2848 }
2849
2850 assert!(errors.iter().all(|message| message.len() < 240));
2851 }
2852
2853 #[rstest]
2854 #[tokio::test]
2855 async fn outbound_subscription_logs_omit_payload_bodies() {
2856 let _capture = capture_logs().await;
2857
2858 let signal = Arc::new(AtomicBool::new(false));
2859 let (cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
2860 let (raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
2861 let (out_tx, _out_rx) = tokio::sync::mpsc::unbounded_channel();
2862 let post_router = PostRouter::new();
2863 let cloid_cache: CloidCache = Arc::new(Mutex::new(FifoCacheMap::<
2864 Ustr,
2865 ClientOrderId,
2866 CLOID_CACHE_CAPACITY,
2867 >::new()));
2868 let mut handler = FeedHandler::new(
2869 signal,
2870 cmd_rx,
2871 raw_rx,
2872 out_tx,
2873 None,
2874 SubscriptionState::new(':'),
2875 cloid_cache,
2876 post_router,
2877 Arc::new(WebSocketRateLimits::new()),
2878 1,
2879 );
2880 let subscription = SubscriptionRequest::Notification {
2881 user: SECRET_MARKER.to_string(),
2882 };
2883 let subscribe_len = serde_json::to_string(&HyperliquidWsRequest::Subscribe {
2884 subscription: subscription.clone(),
2885 })
2886 .unwrap()
2887 .len();
2888 let unsubscribe_len = serde_json::to_string(&HyperliquidWsRequest::Unsubscribe {
2889 subscription: subscription.clone(),
2890 })
2891 .unwrap()
2892 .len();
2893
2894 LOG_CAPTURE.clear();
2895
2896 cmd_tx
2897 .send(HandlerCommand::Subscribe {
2898 subscriptions: vec![subscription.clone()],
2899 })
2900 .unwrap();
2901 cmd_tx
2902 .send(HandlerCommand::Unsubscribe {
2903 subscriptions: vec![subscription],
2904 })
2905 .unwrap();
2906 drop(cmd_tx);
2907 drop(raw_tx);
2908
2909 assert!(handler.next().await.is_none());
2910
2911 let messages: Vec<_> = LOG_CAPTURE
2912 .messages()
2913 .into_iter()
2914 .filter(|message| message.starts_with("Sending "))
2915 .collect();
2916
2917 assert!(
2918 messages
2919 .iter()
2920 .all(|message| !message.contains(SECRET_MARKER)),
2921 "outbound logs exposed the secret marker: {messages:?}"
2922 );
2923 assert!(
2924 messages
2925 .iter()
2926 .any(|message| message
2927 == &format!("Sending subscribe payload ({subscribe_len} bytes)")),
2928 "subscribe metadata missing or inaccurate: {messages:?}"
2929 );
2930 assert!(
2931 messages.iter().any(|message| {
2932 message == &format!("Sending unsubscribe payload ({unsubscribe_len} bytes)")
2933 }),
2934 "unsubscribe metadata missing or inaccurate: {messages:?}"
2935 );
2936 }
2937
2938 pub(in crate::websocket) async fn capture_logs() -> tokio::sync::MutexGuard<'static, ()> {
2939 let guard = LOG_LOCK.lock().await;
2940 LOG_INSTALL.call_once(|| {
2941 log::set_logger(&LOG_CAPTURE).expect("test logger already installed");
2942 log::set_max_level(LevelFilter::Debug);
2943 });
2944
2945 LOG_CAPTURE.clear();
2946 guard
2947 }
2948
2949 pub(in crate::websocket) fn captured_logs() -> Vec<String> {
2950 LOG_CAPTURE.messages()
2951 }
2952
2953 #[tokio::test]
2954 async fn unsubscribe_confirmation_releases_shared_reservation() {
2955 let signal = Arc::new(AtomicBool::new(false));
2956 let (cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
2957 let (raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
2958 let (out_tx, _out_rx) = tokio::sync::mpsc::unbounded_channel();
2959 let subscriptions = SubscriptionState::new(':');
2960 let limits = Arc::new(WebSocketRateLimits::new());
2961 let released = SubscriptionRequest::Trades {
2962 coin: Ustr::from("RELEASED"),
2963 };
2964 let released_key = super::subscription_to_key(&released);
2965 subscriptions.mark_subscribe(&released_key);
2966 subscriptions.confirm_subscribe(&released_key);
2967 subscriptions.mark_unsubscribe(&released_key);
2968 assert!(limits.reserve_subscription(1, &released).unwrap());
2969
2970 for index in 1..HYPERLIQUID_WS_SUBSCRIPTIONS_MAX {
2971 assert!(
2972 limits
2973 .reserve_subscription(
2974 1,
2975 &SubscriptionRequest::Trades {
2976 coin: Ustr::from(&format!("COIN-{index}")),
2977 },
2978 )
2979 .unwrap()
2980 );
2981 }
2982 assert!(
2983 limits
2984 .reserve_subscription(
2985 2,
2986 &SubscriptionRequest::Trades {
2987 coin: Ustr::from("BEFORE-ACK"),
2988 },
2989 )
2990 .is_err()
2991 );
2992
2993 let cloid_cache: CloidCache = Arc::new(Mutex::new(FifoCacheMap::<
2994 Ustr,
2995 ClientOrderId,
2996 CLOID_CACHE_CAPACITY,
2997 >::new()));
2998 let mut handler = FeedHandler::new(
2999 signal,
3000 cmd_rx,
3001 raw_rx,
3002 out_tx,
3003 None,
3004 subscriptions,
3005 cloid_cache,
3006 PostRouter::new(),
3007 Arc::clone(&limits),
3008 1,
3009 );
3010 raw_tx
3011 .send(Message::Text(
3012 json!({
3013 "channel": "subscriptionResponse",
3014 "data": {
3015 "method": "unsubscribe",
3016 "subscription": {
3017 "type": "trades",
3018 "coin": "RELEASED",
3019 },
3020 },
3021 })
3022 .to_string()
3023 .into(),
3024 ))
3025 .unwrap();
3026 drop(raw_tx);
3027 drop(cmd_tx);
3028
3029 assert!(handler.next().await.is_none());
3030 assert!(
3031 limits
3032 .reserve_subscription(
3033 2,
3034 &SubscriptionRequest::Trades {
3035 coin: Ustr::from("AFTER-ACK"),
3036 },
3037 )
3038 .unwrap()
3039 );
3040 }
3041
3042 #[rstest]
3043 fn handle_l2_book_emits_deltas_only_when_not_in_depth_subs() {
3044 let mut instruments = AHashMap::new();
3045 instruments.insert(Ustr::from("BTC"), btc_perp());
3046 let depth_subs = AHashSet::<Ustr>::new();
3047
3048 let msgs = FeedHandler::handle_l2_book(
3049 &one_level_book(),
3050 &instruments,
3051 &depth_subs,
3052 UnixNanos::default(),
3053 );
3054
3055 assert_eq!(msgs.len(), 1);
3056 assert!(matches!(msgs[0], NautilusWsMessage::Deltas(_)));
3057 }
3058
3059 #[rstest]
3060 fn handle_l2_book_emits_deltas_and_depth_when_coin_in_subs() {
3061 let mut instruments = AHashMap::new();
3062 instruments.insert(Ustr::from("BTC"), btc_perp());
3063 let mut depth_subs = AHashSet::<Ustr>::new();
3064 depth_subs.insert(Ustr::from("BTC"));
3065
3066 let msgs = FeedHandler::handle_l2_book(
3067 &one_level_book(),
3068 &instruments,
3069 &depth_subs,
3070 UnixNanos::default(),
3071 );
3072
3073 assert_eq!(msgs.len(), 2);
3074 assert!(matches!(msgs[0], NautilusWsMessage::Deltas(_)));
3075 assert!(matches!(msgs[1], NautilusWsMessage::Depth(_)));
3076 }
3077
3078 #[rstest]
3079 fn handle_l2_book_reports_unparsable_frame_as_invalid_book() {
3080 let instrument = btc_perp();
3081 let instrument_id = instrument.id();
3082 let mut instruments = AHashMap::new();
3083 instruments.insert(Ustr::from("BTC"), instrument);
3084 let mut book = one_level_book();
3085 book.time = u64::MAX;
3086
3087 let msgs = FeedHandler::handle_l2_book(
3088 &book,
3089 &instruments,
3090 &AHashSet::<Ustr>::new(),
3091 UnixNanos::default(),
3092 );
3093
3094 assert_eq!(msgs.len(), 1);
3095 assert!(matches!(
3096 msgs[0],
3097 NautilusWsMessage::BookInvalid { instrument_id: id, .. } if id == instrument_id
3098 ));
3099 }
3100
3101 #[rstest]
3102 fn handle_l2_book_returns_empty_when_instrument_unknown() {
3103 let instruments = AHashMap::<Ustr, InstrumentAny>::new();
3104 let depth_subs = AHashSet::<Ustr>::new();
3105
3106 let msgs = FeedHandler::handle_l2_book(
3107 &one_level_book(),
3108 &instruments,
3109 &depth_subs,
3110 UnixNanos::default(),
3111 );
3112
3113 assert!(msgs.is_empty());
3114 }
3115
3116 #[rstest]
3117 fn handle_asset_context_emits_open_interest_custom_data_when_subscribed() {
3118 let instrument = btc_perp();
3119 let instrument_id = instrument.id();
3120 let mut instruments = AHashMap::new();
3121 instruments.insert(Ustr::from("BTC"), instrument);
3122
3123 let mut asset_context_subs = AHashMap::new();
3124 asset_context_subs.insert(
3125 Ustr::from("BTC"),
3126 AHashSet::from_iter([AssetContextDataType::OpenInterest]),
3127 );
3128
3129 let mut asset_context_caches = AssetContextCaches::default();
3130
3131 let msgs = FeedHandler::handle_asset_context(
3132 &btc_active_asset_ctx(dec!(100000.0)),
3133 &instruments,
3134 &asset_context_subs,
3135 &mut asset_context_caches,
3136 UnixNanos::default(),
3137 );
3138
3139 assert_eq!(msgs.len(), 1);
3140
3141 match &msgs[0] {
3142 NautilusWsMessage::CustomData(Data::Custom(custom)) => {
3143 let open_interest = custom
3144 .data
3145 .as_any()
3146 .downcast_ref::<HyperliquidOpenInterest>()
3147 .expect("expected HyperliquidOpenInterest");
3148 assert_eq!(open_interest.instrument_id, instrument_id);
3149 assert_eq!(open_interest.open_interest.to_string(), "100000.0");
3150 assert_eq!(
3151 custom
3152 .data_type
3153 .metadata()
3154 .and_then(|metadata| metadata.get_str("instrument_id"))
3155 .map(ToString::to_string),
3156 Some(instrument_id.to_string()),
3157 );
3158 }
3159 other => panic!("unexpected message type: {other:?}"),
3160 }
3161 }
3162
3163 #[rstest]
3164 fn handle_all_dexs_asset_ctxs_emits_normalized_custom_data() {
3165 let mapping = AHashMap::from_iter([
3166 (
3167 Ustr::from(""),
3168 vec![Some(InstrumentId::from("BTC-USD-PERP.HYPERLIQUID"))],
3169 ),
3170 (
3171 Ustr::from("xyz"),
3172 vec![Some(InstrumentId::from("xyz:XYZ100-USD-PERP.HYPERLIQUID"))],
3173 ),
3174 ]);
3175
3176 let msg = FeedHandler::handle_all_dexs_asset_ctxs(
3177 sample_all_dexs_asset_ctxs(),
3178 &mapping,
3179 UnixNanos::default(),
3180 )
3181 .expect("expected custom data");
3182
3183 match msg {
3184 NautilusWsMessage::CustomData(Data::Custom(custom)) => {
3185 let payload = custom
3186 .data
3187 .as_any()
3188 .downcast_ref::<HyperliquidAllDexsAssetCtxs>()
3189 .expect("expected HyperliquidAllDexsAssetCtxs");
3190 let btc_impact_prices = payload.entries[0].impact_prices.as_ref().unwrap();
3191 let xyz_impact_prices = payload.entries[1].impact_prices.as_ref().unwrap();
3192
3193 assert_eq!(payload.entries.len(), 2);
3194 assert_eq!(
3195 payload.entries[0].instrument_id,
3196 InstrumentId::from("BTC-USD-PERP.HYPERLIQUID")
3197 );
3198 assert_eq!(payload.entries[1].dex, "xyz");
3199 assert_eq!(
3200 payload.entries[1].instrument_id,
3201 InstrumentId::from("xyz:XYZ100-USD-PERP.HYPERLIQUID")
3202 );
3203 assert_eq!(payload.entries[0].mark_price.to_string(), "77562.0");
3204 assert_eq!(payload.entries[1].day_base_volume.to_string(), "5135.2458");
3205 assert_eq!(btc_impact_prices.bid.as_decimal(), dec!(77558.0));
3206 assert_eq!(btc_impact_prices.ask.as_decimal(), dec!(77559.0));
3207 assert_eq!(xyz_impact_prices.bid.as_decimal(), dec!(29854.0));
3208 assert_eq!(xyz_impact_prices.ask.as_decimal(), dec!(29855.0));
3209 }
3210 other => panic!("expected custom data, found {other:?}"),
3211 }
3212 }
3213
3214 #[rstest]
3215 fn handle_all_dexs_asset_ctxs_preserves_index_alignment_when_mappings_are_missing() {
3216 let data = WsAllDexsAssetCtxsData {
3217 ctxs: vec![(
3218 String::new(),
3219 vec![
3220 PerpsAssetCtx {
3221 shared: SharedAssetCtx {
3222 day_ntl_vlm: dec!(1516669192.1953897476),
3223 prev_day_px: dec!(76317.0),
3224 mark_px: dec!(77562.0),
3225 mid_px: Some(dec!(77558.5)),
3226 impact_pxs: Some(vec![dec!(77558.0), dec!(77559.0)]),
3227 day_base_vlm: Some(dec!(19707.77457)),
3228 },
3229 funding: dec!(-0.0000015186),
3230 open_interest: dec!(27353.17682),
3231 oracle_px: dec!(77605.0),
3232 premium: Some(dec!(-0.0005927453)),
3233 },
3234 PerpsAssetCtx {
3235 shared: SharedAssetCtx {
3236 day_ntl_vlm: dec!(591989409.9392402172),
3237 prev_day_px: dec!(2094.6),
3238 mark_px: dec!(2123.7),
3239 mid_px: Some(dec!(2123.95)),
3240 impact_pxs: Some(vec![dec!(2123.65), dec!(2124.0)]),
3241 day_base_vlm: Some(dec!(281686.8234999999)),
3242 },
3243 funding: dec!(0.0000125),
3244 open_interest: dec!(605822.2557999999),
3245 oracle_px: dec!(2124.6),
3246 premium: Some(dec!(-0.0002824061)),
3247 },
3248 ],
3249 )],
3250 };
3251
3252 let mapping = AHashMap::from_iter([(
3253 Ustr::from(""),
3254 vec![None, Some(InstrumentId::from("ETH-USD-PERP.HYPERLIQUID"))],
3255 )]);
3256
3257 let msg = FeedHandler::handle_all_dexs_asset_ctxs(data, &mapping, UnixNanos::default())
3258 .expect("expected custom data");
3259
3260 match msg {
3261 NautilusWsMessage::CustomData(Data::Custom(custom)) => {
3262 let payload = custom
3263 .data
3264 .as_any()
3265 .downcast_ref::<HyperliquidAllDexsAssetCtxs>()
3266 .expect("expected HyperliquidAllDexsAssetCtxs");
3267 assert_eq!(payload.entries.len(), 1);
3268 assert_eq!(
3269 payload.entries[0].instrument_id,
3270 InstrumentId::from("ETH-USD-PERP.HYPERLIQUID")
3271 );
3272 assert_eq!(payload.entries[0].mark_price.to_string(), "2123.7");
3273 }
3274 other => panic!("expected custom data, found {other:?}"),
3275 }
3276 }
3277
3278 #[rstest]
3279 fn handle_asset_context_skips_open_interest_for_spot_payload() {
3280 let instrument = btc_perp();
3281 let mut instruments = AHashMap::new();
3282 instruments.insert(Ustr::from("BTC"), instrument);
3283
3284 let mut asset_context_subs = AHashMap::new();
3285 asset_context_subs.insert(
3286 Ustr::from("BTC"),
3287 AHashSet::from_iter([AssetContextDataType::OpenInterest]),
3288 );
3289
3290 let mut asset_context_caches = AssetContextCaches::default();
3291
3292 let msgs = FeedHandler::handle_asset_context(
3293 &btc_active_spot_asset_ctx(),
3294 &instruments,
3295 &asset_context_subs,
3296 &mut asset_context_caches,
3297 UnixNanos::default(),
3298 );
3299
3300 assert!(msgs.is_empty());
3301 assert!(asset_context_caches.open_interest.is_empty());
3302 }
3303
3304 #[rstest]
3305 fn handle_asset_context_suppresses_unchanged_open_interest() {
3306 let instrument = btc_perp();
3307 let mut instruments = AHashMap::new();
3308 instruments.insert(Ustr::from("BTC"), instrument);
3309
3310 let mut asset_context_subs = AHashMap::new();
3311 asset_context_subs.insert(
3312 Ustr::from("BTC"),
3313 AHashSet::from_iter([AssetContextDataType::OpenInterest]),
3314 );
3315
3316 let mut asset_context_caches = AssetContextCaches::default();
3317
3318 let first = FeedHandler::handle_asset_context(
3319 &btc_active_asset_ctx(dec!(100000.0)),
3320 &instruments,
3321 &asset_context_subs,
3322 &mut asset_context_caches,
3323 UnixNanos::default(),
3324 );
3325 let second = FeedHandler::handle_asset_context(
3326 &btc_active_asset_ctx(dec!(100000.0)),
3327 &instruments,
3328 &asset_context_subs,
3329 &mut asset_context_caches,
3330 UnixNanos::default(),
3331 );
3332
3333 assert_eq!(first.len(), 1);
3334 assert!(second.is_empty());
3335 }
3336
3337 #[rstest]
3338 fn asset_context_caches_clear_removed_data_types() {
3339 let coin = Ustr::from("BTC");
3340 let mut caches = AssetContextCaches::default();
3341 caches.mark_price.insert(coin, dec!(98455.5));
3342 caches.index_price.insert(coin, dec!(98460.0));
3343 caches.funding_rate.insert(coin, dec!(0.0001));
3344 caches.open_interest.insert(coin, dec!(1500.0));
3345
3346 let previous_data_types = AHashSet::from_iter([
3347 AssetContextDataType::MarkPrice,
3348 AssetContextDataType::IndexPrice,
3349 AssetContextDataType::FundingRate,
3350 AssetContextDataType::OpenInterest,
3351 ]);
3352 let next_data_types = AHashSet::from_iter([
3353 AssetContextDataType::MarkPrice,
3354 AssetContextDataType::FundingRate,
3355 ]);
3356
3357 caches.clear_removed(coin, Some(&previous_data_types), &next_data_types);
3358
3359 assert_eq!(caches.mark_price.get(&coin).copied(), Some(dec!(98455.5)));
3360 assert!(caches.index_price.get(&coin).is_none());
3361 assert_eq!(caches.funding_rate.get(&coin).copied(), Some(dec!(0.0001)));
3362 assert!(caches.open_interest.get(&coin).is_none());
3363 }
3364}