Skip to main content

nautilus_hyperliquid/websocket/
handler.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! WebSocket message handler for Hyperliquid.
17
18use 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/// Commands sent from the outer client to the inner message handler.
80#[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    /// Installs the WebSocket client and acknowledges initialization.
88    SetClient {
89        client: WebSocketClient,
90        initialized: tokio::sync::oneshot::Sender<()>,
91    },
92    /// Disconnect the WebSocket connection.
93    Disconnect,
94    /// Subscribe to the given subscriptions.
95    Subscribe {
96        subscriptions: Vec<SubscriptionRequest>,
97    },
98    /// Unsubscribe from the given subscriptions.
99    Unsubscribe {
100        subscriptions: Vec<SubscriptionRequest>,
101    },
102    /// Resubscribes without interleaving handler input between the two sends.
103    Resubscribe { subscription: SubscriptionRequest },
104    /// Writes a book subscription on the current connection, opening `gate` once written.
105    ///
106    /// With `replace`, sends the unsubscribe first so the venue restarts the stream with a
107    /// snapshot. The write always runs, since the stream registry already counts it; `cancel`
108    /// only keeps the gate closed.
109    WriteBook {
110        subscription: SubscriptionRequest,
111        replace: bool,
112        cancel: CancellationToken,
113        gate: SnapshotGate,
114        completion: tokio::sync::oneshot::Sender<Result<(), HyperliquidWsError>>,
115    },
116    /// Send a WebSocket post request.
117    Post {
118        id: u64,
119        request: PostRequest,
120        deadline: tokio::time::Instant,
121        cancellation_token: CancellationToken,
122    },
123    /// Initialize the instruments cache with the given instruments.
124    InitializeInstruments(Vec<InstrumentAny>),
125    /// Update a single instrument in the cache.
126    UpdateInstrument(InstrumentAny),
127    /// Add a bar type mapping for candle parsing.
128    AddBarType { key: String, bar_type: BarType },
129    /// Remove a bar type mapping.
130    RemoveBarType { key: String },
131    /// Update asset context subscriptions for a coin.
132    UpdateAssetContextSubs {
133        coin: Ustr,
134        data_types: AHashSet<AssetContextDataType>,
135    },
136    /// Update the logical consumers of a `trades` stream for a coin.
137    UpdateTradeSubs { coin: Ustr, uses: TradeStreamUses },
138    /// Cache the ordered instrument IDs needed to normalize `allDexsAssetCtxs`.
139    CacheAllDexAssetCtxsInstrumentIds(AHashMap<Ustr, Vec<Option<InstrumentId>>>),
140    /// Cache spot fill coin mappings for instrument lookup.
141    CacheSpotFillCoins(AHashMap<Ustr, Ustr>),
142    /// Flag whether the book stream for `coin` should also publish native depth snapshots.
143    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    /// Creates a new [`FeedHandler`] instance.
279    #[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    /// Send a message to the output channel.
334    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    /// Check if the handler has received a stop signal.
341    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                            // The registry already counts the stream, so skipping or interrupting
425                            // the write could leave a stream that depth shares unsubscribed; a
426                            // later queued unsubscribe settles the final state instead.
427                            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                            // merge by dex to match the client cache, so a partial
536                            // mapping keeps the entries of dexes it did not cover
537                            self.all_dex_asset_ctxs_instrument_ids.extend(mappings);
538                        }
539                        HandlerCommand::CacheSpotFillCoins(_) => {
540                            // No longer needed - raw_symbol now contains the proper format
541                        }
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                                        // A rejection has no subscribe ACK to retire its pending operation
618                                        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        // Retire outputs already queued before this physical stream is replaced or removed
699        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        // Old ACKs cannot admit frames into a replacement subscription's baseline
744        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        // A malformed compressed frame cannot reliably identify its affected coin
757        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            // Keeps the stream desired for reconnect replay; its unsubscribe ack is then stale
900            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                // Process fills from userEvents channel (userFills channel is redundant)
997                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                // UserFills channel is redundant with userEvents, but handle it for
1037                // backwards compatibility if explicitly subscribed
1038                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                    // Take instead of clone on the last subscriber
1083                    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            // Ignore other message types (subscription confirmations, etc)
1156            _ => {}
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                        // Resolve cloid to real client_order_id if cached
1179                        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                        // Mark processed only after successful parse
1228                        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                // Not marked as processed so fill is retried if instrument loads later
1254                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            // Emit cached bar when close_time changes, indicating the previous period closed
1394            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                // Mapping is rebuilt on each instrument refresh, instrument request, and data
1547                // client connect, so a count change means the universe drifted since the last
1548                // build and positional alignment can no longer be trusted until the next one.
1549                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        // Error Display can echo private values, including unknown tags and invalid fields
1777        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    // Spot acknowledgements omit isPortfolioMargin; retain the tracked request's flag
1886    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
1991/// Determines whether a Hyperliquid WebSocket error should trigger a retry.
1992pub(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
2011/// Creates a timeout error for Hyperliquid retry logic.
2012pub(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        // The first subscribe ACK belongs to the stream replaced before confirmation
2237        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        // A delta subscription replaces an existing depth stream before the old output is read
2328        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        // No client is set, so the write fails before any send
2561        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}