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