Skip to main content

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