Skip to main content

nautilus_architect_ax/websocket/data/
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//! Market data WebSocket message handler for Ax.
17
18use std::{
19    collections::VecDeque,
20    sync::{
21        Arc,
22        atomic::{AtomicBool, Ordering},
23    },
24};
25
26use ahash::AHashMap;
27use futures_util::future::BoxFuture;
28use nautilus_live::book::snapshot::SnapshotGate;
29use nautilus_network::websocket::{SubscriptionState, WebSocketClient};
30use tokio_tungstenite::tungstenite::Message;
31use tokio_util::sync::CancellationToken;
32use ustr::Ustr;
33
34use super::{AxMdSubscriptionSpec, AxWsClientError};
35use crate::{
36    common::enums::{AxCandleWidth, AxMdRequestType},
37    websocket::{
38        messages::{
39            AxDataWsMessage, AxMdMessage, AxMdSubscribe, AxMdSubscribeCandles, AxMdUnsubscribe,
40            AxMdUnsubscribeCandles,
41        },
42        parse::parse_md_message,
43    },
44};
45
46const BOOK_WRITE_CANCELED: &str = "Book write canceled";
47
48/// Commands sent from the outer client to the inner message handler.
49#[derive(Debug)]
50pub enum HandlerCommand {
51    /// Set the WebSocket client for this handler.
52    SetClient(WebSocketClient),
53    /// Disconnect the WebSocket connection.
54    Disconnect,
55    /// Replay all subscriptions after a reconnection.
56    ReplaySubscriptions,
57    /// Subscribe to market data for a symbol.
58    Subscribe {
59        request_id: i64,
60        symbol: Ustr,
61        spec: AxMdSubscriptionSpec,
62    },
63    /// Writes a book subscription on the current connection, opening `gate` once written.
64    ///
65    /// With an unsubscribe request ID, first unsubscribes the symbol so the venue restarts its
66    /// stream with a snapshot. That acknowledgement stays untracked, keeping the topic desired for
67    /// reconnect replay. Cancellation skips unsent work and keeps the gate closed. A write already
68    /// admitted to the network can still complete, ahead of later subscription changes.
69    WriteBook {
70        request_id: i64,
71        unsubscribe_request_id: Option<i64>,
72        symbol: Ustr,
73        spec: AxMdSubscriptionSpec,
74        cancel: CancellationToken,
75        gate: SnapshotGate,
76        completion: tokio::sync::oneshot::Sender<Result<(), AxWsClientError>>,
77    },
78    /// Unsubscribe from market data for a symbol.
79    Unsubscribe {
80        request_id: i64,
81        symbol: Ustr,
82        topic: String,
83    },
84    /// Subscribe to candle data for a symbol.
85    SubscribeCandles {
86        request_id: i64,
87        symbol: Ustr,
88        width: AxCandleWidth,
89    },
90    /// Unsubscribe from candle data for a symbol.
91    UnsubscribeCandles {
92        request_id: i64,
93        symbol: Ustr,
94        width: AxCandleWidth,
95        topic: String,
96    },
97}
98
99/// Market data feed handler that processes WebSocket messages.
100///
101/// Runs in a dedicated Tokio task and owns the WebSocket client exclusively.
102/// Emits raw venue types for downstream consumers to parse.
103pub(crate) struct AxMdWsFeedHandler {
104    signal: Arc<AtomicBool>,
105    inner: Option<Arc<WebSocketClient>>,
106    cmd_rx: tokio::sync::mpsc::UnboundedReceiver<HandlerCommand>,
107    raw_rx: tokio::sync::mpsc::UnboundedReceiver<Message>,
108    subscriptions: SubscriptionState,
109    message_queue: VecDeque<AxDataWsMessage>,
110    replay_request_id: i64,
111    needs_subscription_replay: bool,
112    pending_subscription_requests: AHashMap<i64, PendingSubscriptionRequest>,
113    writes: VecDeque<PendingWrite>,
114}
115
116impl AxMdWsFeedHandler {
117    /// Creates a new [`AxMdWsFeedHandler`] instance.
118    #[must_use]
119    pub(crate) fn new(
120        signal: Arc<AtomicBool>,
121        cmd_rx: tokio::sync::mpsc::UnboundedReceiver<HandlerCommand>,
122        raw_rx: tokio::sync::mpsc::UnboundedReceiver<Message>,
123        subscriptions: SubscriptionState,
124    ) -> Self {
125        Self {
126            signal,
127            inner: None,
128            cmd_rx,
129            raw_rx,
130            subscriptions,
131            message_queue: VecDeque::new(),
132            replay_request_id: -1,
133            needs_subscription_replay: false,
134            pending_subscription_requests: AHashMap::new(),
135            writes: VecDeque::new(),
136        }
137    }
138
139    fn next_replay_request_id(&mut self) -> i64 {
140        self.replay_request_id -= 1;
141        self.replay_request_id
142    }
143
144    fn replay_subscriptions(&mut self) {
145        self.pending_subscription_requests.clear();
146        let topics = self.subscriptions.reset_after_reconnect();
147        if topics.is_empty() {
148            log::debug!("No subscriptions to replay after reconnect");
149            return;
150        }
151
152        log::debug!("Replaying {} subscriptions after reconnect", topics.len());
153
154        for topic in topics {
155            // Topic format: "symbol:Level:trades:ticker" or "candles:symbol:Width"
156            if let Some(rest) = topic.strip_prefix("candles:") {
157                if let Some((symbol, width_str)) = rest.rsplit_once(':') {
158                    if let Some(width) = Self::parse_candle_width(width_str) {
159                        let request_id = self.next_replay_request_id();
160                        log::debug!(
161                            "Replaying candle subscription: symbol={symbol}, width={width:?}"
162                        );
163                        self.pending_subscription_requests.insert(
164                            request_id,
165                            PendingSubscriptionRequest::Subscribe(topic.clone()),
166                        );
167                        self.send_subscribe_candles(request_id, Ustr::from(symbol), width);
168                    } else {
169                        log::warn!("Failed to parse candle width from topic: {topic}");
170                    }
171                } else {
172                    log::warn!("Invalid candle topic format: {topic}");
173                }
174            } else if let Some((symbol, spec)) = AxMdSubscriptionSpec::parse_topic(&topic) {
175                let request_id = self.next_replay_request_id();
176                log::debug!("Replaying market data subscription: symbol={symbol}, spec={spec:?}");
177                self.pending_subscription_requests
178                    .insert(request_id, PendingSubscriptionRequest::Subscribe(topic));
179                self.send_subscribe(request_id, symbol, spec);
180            } else {
181                log::warn!("Failed to parse market data subscription topic: {topic}");
182            }
183        }
184
185        log::debug!("Subscription replay completed");
186    }
187
188    fn parse_candle_width(s: &str) -> Option<AxCandleWidth> {
189        match s {
190            "Seconds1" => Some(AxCandleWidth::Seconds1),
191            "Seconds5" => Some(AxCandleWidth::Seconds5),
192            "Minutes1" => Some(AxCandleWidth::Minutes1),
193            "Minutes5" => Some(AxCandleWidth::Minutes5),
194            "Minutes15" => Some(AxCandleWidth::Minutes15),
195            "Hours1" => Some(AxCandleWidth::Hours1),
196            "Days1" => Some(AxCandleWidth::Days1),
197            _ => None,
198        }
199    }
200
201    /// Returns the next message from the handler.
202    ///
203    /// This method blocks until a message is available or the handler is stopped.
204    pub(crate) async fn next(&mut self) -> Option<AxDataWsMessage> {
205        loop {
206            if self.needs_subscription_replay && self.message_queue.is_empty() {
207                self.needs_subscription_replay = false;
208                self.replay_subscriptions();
209            }
210
211            if let Some(msg) = self.message_queue.pop_front() {
212                return Some(msg);
213            }
214
215            tokio::select! {
216                biased;
217
218                failed = async {
219                    match self.writes.front_mut() {
220                        Some(write) => (&mut write.future).await,
221                        None => std::future::pending().await,
222                    }
223                } => {
224                    let write = self.writes.pop_front();
225
226                    if let Some(request_id) = failed {
227                        self.pending_subscription_requests.remove(&request_id);
228                    } else if let Some(write) = write
229                        && let Some((_, Some(snapshot))) = write.book
230                    {
231                        self.message_queue.push_back(snapshot);
232                    }
233                }
234
235                Some(cmd) = self.cmd_rx.recv() => {
236                    self.handle_command(cmd).await;
237                }
238
239                () = tokio::time::sleep(std::time::Duration::from_millis(100)) => {
240                    if self.signal.load(Ordering::Acquire) {
241                        log::debug!("Stop signal received during idle period");
242                        return None;
243                    }
244                }
245
246                msg = self.raw_rx.recv() => {
247                    let msg = match msg {
248                        Some(msg) => msg,
249                        None => {
250                            log::debug!("WebSocket stream closed");
251                            return None;
252                        }
253                    };
254
255                    if let Message::Ping(data) = &msg {
256                        log::trace!("Received ping frame with {} bytes", data.len());
257
258                        if let Some(client) = &self.inner
259                            && let Err(e) = client.send_pong(data.to_vec()).await
260                        {
261                            log::warn!("Failed to send pong frame: {e}");
262                        }
263                        continue;
264                    }
265
266                    if let Some(message) = self.parse_raw_message(msg) {
267                        self.queue_message(message);
268                    }
269
270                    if self.signal.load(Ordering::Acquire) {
271                        log::debug!("Stop signal received");
272                        return None;
273                    }
274                }
275            }
276        }
277    }
278
279    fn queue_message(&mut self, message: AxDataWsMessage) {
280        let symbol = match &message {
281            AxDataWsMessage::MdMessage(AxMdMessage::BookL2(book)) if book.st => Some(book.s),
282            AxDataWsMessage::MdMessage(AxMdMessage::BookL3(book)) if book.st => Some(book.s),
283            _ => None,
284        };
285
286        if let Some((pending_symbol, snapshot)) = self
287            .writes
288            .front_mut()
289            .and_then(|write| write.book.as_mut())
290            && symbol == Some(*pending_symbol)
291        {
292            *snapshot = Some(message);
293        } else {
294            self.message_queue.push_back(message);
295        }
296    }
297
298    async fn handle_command(&mut self, cmd: HandlerCommand) {
299        match cmd {
300            HandlerCommand::SetClient(client) => {
301                log::debug!("WebSocketClient received by handler");
302                self.inner = Some(Arc::new(client));
303            }
304            HandlerCommand::Disconnect => {
305                log::debug!("Disconnect command received");
306                self.writes.clear();
307
308                if let Some(inner) = self.inner.take() {
309                    inner.disconnect().await;
310                }
311            }
312            HandlerCommand::ReplaySubscriptions => {
313                log::debug!("ReplaySubscriptions command received");
314                self.replay_subscriptions();
315            }
316            HandlerCommand::Subscribe {
317                request_id,
318                symbol,
319                spec,
320            } => {
321                log::debug!(
322                    "Subscribe command received: request_id={request_id}, symbol={symbol}, spec={spec:?}"
323                );
324                let topic = spec.topic(symbol.as_str());
325                self.pending_subscription_requests
326                    .insert(request_id, PendingSubscriptionRequest::Subscribe(topic));
327                self.send_subscribe(request_id, symbol, spec);
328            }
329            HandlerCommand::WriteBook {
330                request_id,
331                unsubscribe_request_id,
332                symbol,
333                spec,
334                cancel,
335                gate,
336                completion,
337            } => {
338                log::debug!(
339                    "WriteBook command received: request_id={request_id}, symbol={symbol}, spec={spec:?}"
340                );
341
342                if cancel.is_cancelled() {
343                    let _ = completion.send(Err(AxWsClientError::ClientError(
344                        BOOK_WRITE_CANCELED.to_string(),
345                    )));
346                    return;
347                }
348
349                let Some(client) = self.inner.clone() else {
350                    let _ = completion.send(Err(AxWsClientError::Transport(
351                        "No WebSocket client available".to_string(),
352                    )));
353                    return;
354                };
355
356                let epoch = client.connection_epoch();
357                let topic = spec.topic(symbol.as_str());
358                let subscriptions = self.subscriptions.clone();
359                self.pending_subscription_requests
360                    .insert(request_id, PendingSubscriptionRequest::Subscribe(topic));
361
362                let future = Box::pin(async move {
363                    let result = write_book(
364                        &client,
365                        &subscriptions,
366                        request_id,
367                        unsubscribe_request_id,
368                        symbol,
369                        spec,
370                        epoch,
371                        &cancel,
372                    )
373                    .await;
374
375                    let written = result.is_ok() && !cancel.is_cancelled();
376                    if written {
377                        gate.open();
378                    }
379
380                    let _ = completion.send(result);
381                    (!written).then_some(request_id)
382                });
383
384                self.writes.push_back(PendingWrite {
385                    future,
386                    book: Some((symbol, None)),
387                });
388            }
389            HandlerCommand::Unsubscribe {
390                request_id,
391                symbol,
392                topic,
393            } => {
394                log::debug!(
395                    "Unsubscribe command received: request_id={request_id}, symbol={symbol}"
396                );
397                self.pending_subscription_requests
398                    .insert(request_id, PendingSubscriptionRequest::Unsubscribe(topic));
399                self.send_unsubscribe(request_id, symbol);
400            }
401            HandlerCommand::SubscribeCandles {
402                request_id,
403                symbol,
404                width,
405            } => {
406                log::debug!(
407                    "SubscribeCandles command received: request_id={request_id}, symbol={symbol}, width={width:?}"
408                );
409                let topic = format!("candles:{symbol}:{width:?}");
410                self.pending_subscription_requests
411                    .insert(request_id, PendingSubscriptionRequest::Subscribe(topic));
412                self.send_subscribe_candles(request_id, symbol, width);
413            }
414            HandlerCommand::UnsubscribeCandles {
415                request_id,
416                symbol,
417                width,
418                topic,
419            } => {
420                log::debug!(
421                    "UnsubscribeCandles command received: request_id={request_id}, symbol={symbol}, width={width:?}"
422                );
423                self.pending_subscription_requests
424                    .insert(request_id, PendingSubscriptionRequest::Unsubscribe(topic));
425                self.message_queue
426                    .push_back(AxDataWsMessage::CandleUnsubscribed { symbol, width });
427                self.send_unsubscribe_candles(request_id, symbol, width);
428            }
429        }
430    }
431
432    fn send_subscribe(&mut self, request_id: i64, symbol: Ustr, spec: AxMdSubscriptionSpec) {
433        let msg = AxMdSubscribe {
434            rid: request_id,
435            msg_type: AxMdRequestType::Subscribe,
436            symbol,
437            level: spec.level,
438            trades: spec.trades,
439            ticker: spec.ticker,
440        };
441
442        if let Err(e) = self.send_json(request_id, &msg) {
443            self.pending_subscription_requests.remove(&request_id);
444            log::error!("Failed to send subscribe message: {e}");
445        }
446    }
447
448    fn send_unsubscribe(&mut self, request_id: i64, symbol: Ustr) {
449        let msg = AxMdUnsubscribe {
450            rid: request_id,
451            msg_type: AxMdRequestType::Unsubscribe,
452            symbol,
453        };
454
455        if let Err(e) = self.send_json(request_id, &msg) {
456            self.pending_subscription_requests.remove(&request_id);
457            log::error!("Failed to send unsubscribe message: {e}");
458        }
459    }
460
461    fn send_subscribe_candles(&mut self, request_id: i64, symbol: Ustr, width: AxCandleWidth) {
462        let msg = AxMdSubscribeCandles {
463            rid: request_id,
464            msg_type: AxMdRequestType::SubscribeCandles,
465            symbol,
466            width,
467        };
468
469        if let Err(e) = self.send_json(request_id, &msg) {
470            self.pending_subscription_requests.remove(&request_id);
471            log::error!("Failed to send subscribe_candles message: {e}");
472        }
473    }
474
475    fn send_unsubscribe_candles(&mut self, request_id: i64, symbol: Ustr, width: AxCandleWidth) {
476        let msg = AxMdUnsubscribeCandles {
477            rid: request_id,
478            msg_type: AxMdRequestType::UnsubscribeCandles,
479            symbol,
480            width,
481        };
482
483        if let Err(e) = self.send_json(request_id, &msg) {
484            self.pending_subscription_requests.remove(&request_id);
485            log::error!("Failed to send unsubscribe_candles message: {e}");
486        }
487    }
488
489    fn send_json<T: serde::Serialize>(&mut self, request_id: i64, msg: &T) -> Result<(), String> {
490        let Some(inner) = self.inner.clone() else {
491            return Err("No WebSocket client available".to_string());
492        };
493
494        let payload = serde_json::to_string(msg).map_err(|e| e.to_string())?;
495        log::trace!("Sending WebSocket payload ({} bytes)", payload.len());
496
497        let future = Box::pin(async move {
498            if let Err(e) = inner.send_text(payload, None).await {
499                log::error!("Failed to send subscription message: {e}");
500                return Some(request_id);
501            }
502
503            None
504        });
505
506        self.writes.push_back(PendingWrite { future, book: None });
507
508        Ok(())
509    }
510
511    fn parse_raw_message(&mut self, msg: Message) -> Option<AxDataWsMessage> {
512        match msg {
513            Message::Text(text) => {
514                if text == nautilus_network::RECONNECTED {
515                    log::info!("Received WebSocket reconnected signal");
516                    self.needs_subscription_replay = true;
517                    return Some(AxDataWsMessage::Reconnected);
518                }
519
520                log::trace!("Raw websocket message: {text}");
521
522                match parse_md_message(&text) {
523                    Ok(message) => self.handle_message(message),
524                    Err(e) => {
525                        log::error!("Failed to parse WebSocket message: {e}: {text}");
526                        None
527                    }
528                }
529            }
530            Message::Binary(data) => {
531                log::debug!("Received binary message with {} bytes", data.len());
532                None
533            }
534            Message::Close(_) => {
535                log::debug!("Received close message, waiting for reconnection");
536                None
537            }
538            _ => None,
539        }
540    }
541
542    fn handle_message(&mut self, message: AxMdMessage) -> Option<AxDataWsMessage> {
543        match &message {
544            AxMdMessage::Error(error) => {
545                let is_benign = error.message.contains("already subscribed")
546                    || error.message.contains("not subscribed");
547
548                if let Some(rid) = error.request_id
549                    && let Some(request) = self.pending_subscription_requests.remove(&rid)
550                {
551                    match request {
552                        PendingSubscriptionRequest::Subscribe(topic) => {
553                            self.subscriptions.mark_failure(&topic);
554                        }
555                        PendingSubscriptionRequest::Unsubscribe(topic) => {
556                            self.subscriptions.confirm_unsubscribe(&topic);
557                        }
558                    }
559                }
560
561                if is_benign {
562                    log::warn!("Subscription state: {}", error.message);
563                } else {
564                    log::error!("Received error from exchange: {}", error.message);
565                }
566            }
567            AxMdMessage::SubscriptionResponse(response) => {
568                let is_subscribe = response.result.subscribed.is_some()
569                    || response.result.subscribed_candle.is_some();
570                let is_unsubscribe = response.result.unsubscribed.is_some()
571                    || response.result.unsubscribed_candle.is_some();
572
573                if let Some(request) = self.pending_subscription_requests.remove(&response.rid) {
574                    match request {
575                        PendingSubscriptionRequest::Subscribe(topic) if is_subscribe => {
576                            self.subscriptions.confirm_subscribe(&topic);
577                        }
578                        PendingSubscriptionRequest::Unsubscribe(topic) if is_unsubscribe => {
579                            self.subscriptions.confirm_unsubscribe(&topic);
580                        }
581                        request => {
582                            log::warn!(
583                                "Unexpected subscription response for request: {request:?}, \
584                                 response={response:?}"
585                            );
586                        }
587                    }
588                }
589
590                if let Some(symbol) = &response.result.subscribed {
591                    log::debug!("Subscription confirmed for symbol: {symbol}");
592                } else if let Some(candle) = &response.result.subscribed_candle {
593                    log::debug!("Candle subscription confirmed: {candle}");
594                } else if let Some(symbol) = &response.result.unsubscribed {
595                    log::debug!("Unsubscription confirmed for symbol: {symbol}");
596                } else if let Some(candle) = &response.result.unsubscribed_candle {
597                    log::debug!("Candle unsubscription confirmed: {candle}");
598                }
599                return None;
600            }
601            _ => {}
602        }
603
604        Some(AxDataWsMessage::MdMessage(message))
605    }
606}
607
608#[derive(Debug)]
609enum PendingSubscriptionRequest {
610    Subscribe(String),
611    Unsubscribe(String),
612}
613
614struct PendingWrite {
615    future: BoxFuture<'static, Option<i64>>,
616    book: Option<(Ustr, Option<AxDataWsMessage>)>,
617}
618
619#[expect(
620    clippy::too_many_arguments,
621    reason = "the queued write retains its subscription, connection, and cancellation ownership"
622)]
623async fn write_book(
624    client: &WebSocketClient,
625    subscriptions: &SubscriptionState,
626    request_id: i64,
627    unsubscribe_request_id: Option<i64>,
628    symbol: Ustr,
629    spec: AxMdSubscriptionSpec,
630    epoch: u64,
631    cancel: &CancellationToken,
632) -> Result<(), AxWsClientError> {
633    if cancel.is_cancelled() {
634        return Err(AxWsClientError::ClientError(
635            BOOK_WRITE_CANCELED.to_string(),
636        ));
637    }
638
639    if let Some(rid) = unsubscribe_request_id {
640        let topic = spec.topic(symbol.as_str());
641
642        // Keeps the topic desired for reconnect replay, so its subscribe ack confirms it again
643        subscriptions.mark_failure(&topic);
644
645        let msg = AxMdUnsubscribe {
646            rid,
647            msg_type: AxMdRequestType::Unsubscribe,
648            symbol,
649        };
650
651        send_json_on_connection(client, &msg, epoch, cancel).await?;
652    }
653
654    let msg = AxMdSubscribe {
655        rid: request_id,
656        msg_type: AxMdRequestType::Subscribe,
657        symbol,
658        level: spec.level,
659        trades: spec.trades,
660        ticker: spec.ticker,
661    };
662
663    send_json_on_connection(client, &msg, epoch, cancel).await?;
664
665    if client.connection_epoch() != epoch || !client.is_active() {
666        return Err(AxWsClientError::Transport(
667            "Book subscription connection changed".to_string(),
668        ));
669    }
670
671    Ok(())
672}
673
674// Sends once on the connection identified by `epoch`, never replaying on a replacement
675async fn send_json_on_connection<T: serde::Serialize>(
676    client: &WebSocketClient,
677    msg: &T,
678    epoch: u64,
679    cancel: &CancellationToken,
680) -> Result<(), AxWsClientError> {
681    let payload =
682        serde_json::to_string(msg).map_err(|e| AxWsClientError::ClientError(e.to_string()))?;
683
684    tokio::select! {
685        biased;
686        () = cancel.cancelled() => {
687            Err(AxWsClientError::ClientError(BOOK_WRITE_CANCELED.to_string()))
688        }
689        result = client.send_text_on_connection(payload, None, epoch) => {
690            result.map_err(|e| AxWsClientError::Transport(e.to_string()))
691        }
692    }
693}
694
695#[cfg(test)]
696mod tests {
697    use std::time::Duration;
698
699    use futures_util::{StreamExt, poll};
700    use nautilus_network::{
701        mode::ConnectionMode,
702        websocket::{SubscriptionState, TransportBackend, WebSocketConfig},
703    };
704    use rstest::rstest;
705
706    use super::*;
707    use crate::{common::enums::AxMarketDataLevel, websocket::messages::AxWsError};
708
709    const TOPIC: &str = "EURUSD-PERP:Level2:false:false";
710
711    #[rstest]
712    fn test_unsubscribe_error_confirms_removal() {
713        let subscriptions = SubscriptionState::new(':');
714        subscriptions.mark_subscribe(TOPIC);
715        subscriptions.confirm_subscribe(TOPIC);
716        subscriptions.mark_unsubscribe(TOPIC);
717        let mut handler = create_handler(subscriptions.clone());
718        handler.pending_subscription_requests.insert(
719            4,
720            PendingSubscriptionRequest::Unsubscribe(TOPIC.to_string()),
721        );
722
723        handler.handle_message(AxMdMessage::Error(AxWsError {
724            code: Some("400".to_string()),
725            message: "subscription failed".to_string(),
726            request_id: Some(4),
727        }));
728
729        assert_eq!(subscriptions.len(), 0);
730        assert!(subscriptions.pending_subscribe_topics().is_empty());
731        assert!(subscriptions.pending_unsubscribe_topics().is_empty());
732    }
733
734    #[rstest]
735    #[tokio::test]
736    async fn test_replay_clears_stale_requests_and_pending_unsubscribes() {
737        let subscriptions = SubscriptionState::new(':');
738        subscriptions.mark_subscribe(TOPIC);
739        subscriptions.confirm_subscribe(TOPIC);
740        subscriptions.mark_unsubscribe(TOPIC);
741        let mut handler = create_handler(subscriptions.clone());
742        handler.pending_subscription_requests.insert(
743            6,
744            PendingSubscriptionRequest::Unsubscribe(TOPIC.to_string()),
745        );
746
747        handler.replay_subscriptions();
748
749        assert_eq!(subscriptions.len(), 0);
750        assert!(subscriptions.all_topics().is_empty());
751        assert!(subscriptions.pending_subscribe_topics().is_empty());
752        assert!(subscriptions.pending_unsubscribe_topics().is_empty());
753        assert!(handler.pending_subscription_requests.is_empty());
754    }
755
756    #[rstest]
757    #[tokio::test]
758    async fn test_write_book_canceled_before_admission() {
759        let mut handler = create_handler(SubscriptionState::new(':'));
760        let cancel = CancellationToken::new();
761        cancel.cancel();
762        let gate = SnapshotGate::default();
763        gate.lock().close();
764        let (completion, receiver) = tokio::sync::oneshot::channel();
765
766        handler
767            .handle_command(HandlerCommand::WriteBook {
768                request_id: 9,
769                unsubscribe_request_id: Some(10),
770                symbol: Ustr::from("EURUSD-PERP"),
771                spec: AxMdSubscriptionSpec::new(AxMarketDataLevel::Level2, Some(false), Some(true)),
772                cancel,
773                gate: gate.clone(),
774                completion,
775            })
776            .await;
777
778        let result = receiver.await.unwrap();
779
780        assert!(matches!(
781            result,
782            Err(AxWsClientError::ClientError(message)) if message == "Book write canceled"
783        ));
784        assert!(gate.lock().is_closed());
785        assert!(handler.pending_subscription_requests.is_empty());
786    }
787
788    #[rstest]
789    #[tokio::test]
790    async fn test_write_book_failure_keeps_gate_closed() {
791        let mut handler = create_handler(SubscriptionState::new(':'));
792        let gate = SnapshotGate::default();
793        gate.lock().close();
794        let (completion, receiver) = tokio::sync::oneshot::channel();
795
796        // No client is set, so the write fails before any send
797        handler
798            .handle_command(HandlerCommand::WriteBook {
799                request_id: 7,
800                unsubscribe_request_id: Some(8),
801                symbol: Ustr::from("EURUSD-PERP"),
802                spec: AxMdSubscriptionSpec::new(
803                    AxMarketDataLevel::Level2,
804                    Some(false),
805                    Some(false),
806                ),
807                cancel: CancellationToken::new(),
808                gate: gate.clone(),
809                completion,
810            })
811            .await;
812
813        let result = receiver.await.unwrap();
814
815        assert!(matches!(
816            result,
817            Err(AxWsClientError::Transport(message)) if message == "No WebSocket client available"
818        ));
819        assert!(gate.lock().is_closed());
820        assert!(handler.pending_subscription_requests.is_empty());
821    }
822
823    #[rstest]
824    #[case(AxMarketDataLevel::Level2, include_str!("../../../test_data/ws_md_book_l2.json"), false)]
825    #[case(AxMarketDataLevel::Level3, include_str!("../../../test_data/ws_md_book_l3.json"), false)]
826    #[case(AxMarketDataLevel::Level2, include_str!("../../../test_data/ws_md_book_l2.json"), true)]
827    #[tokio::test]
828    async fn test_book_snapshot_waits_for_write_confirmation(
829        #[case] level: AxMarketDataLevel,
830        #[case] fixture: &str,
831        #[case] canceled: bool,
832    ) {
833        let mut connection = HandlerConnection::new().await;
834        let cancel = CancellationToken::new();
835        let (mut command, gate, result) = book_command(cancel.clone());
836
837        let HandlerCommand::WriteBook { spec, .. } = &mut command else {
838            unreachable!();
839        };
840
841        spec.level = level;
842        connection.handler.handle_command(command).await;
843        let (release, held) = tokio::sync::oneshot::channel();
844        let mut write = connection.handler.writes.pop_front().unwrap();
845        let future = write.future;
846        write.future = Box::pin(async move {
847            held.await.unwrap();
848            future.await
849        });
850
851        connection.handler.writes.push_back(write);
852
853        let mut expected: serde_json::Value = serde_json::from_str(fixture).unwrap();
854        connection
855            .frames
856            .send(Message::Text(expected.to_string().into()))
857            .unwrap();
858        connection.frame().await;
859        expected["ts"] = 1609459201_i64.into();
860        connection
861            .frames
862            .send(Message::Text(expected.to_string().into()))
863            .unwrap();
864        connection.frame().await;
865        assert!(gate.lock().is_closed());
866
867        let mut other = expected.clone();
868        other["s"] = "GBPUSD-PERP".into();
869        connection
870            .frames
871            .send(Message::Text(other.to_string().into()))
872            .unwrap();
873        let delivered = tokio::time::timeout(Duration::from_secs(2), connection.handler.next())
874            .await
875            .unwrap()
876            .unwrap();
877        assert_eq!(
878            book_value(delivered),
879            book_value(AxDataWsMessage::MdMessage(
880                parse_md_message(&other.to_string()).unwrap(),
881            ))
882        );
883
884        if canceled {
885            cancel.cancel();
886        }
887
888        release.send(()).unwrap();
889
890        if canceled {
891            connection.frame().await;
892            assert!(
893                matches!(result.await.unwrap(), Err(AxWsClientError::ClientError(message)) if message == "Book write canceled")
894            );
895            assert!(gate.lock().is_closed());
896        } else {
897            let delivered = tokio::time::timeout(Duration::from_secs(2), connection.handler.next())
898                .await
899                .unwrap()
900                .unwrap();
901            assert_eq!(
902                book_value(delivered),
903                book_value(AxDataWsMessage::MdMessage(
904                    parse_md_message(&expected.to_string()).unwrap(),
905                ))
906            );
907            assert!(result.await.unwrap().is_ok());
908            assert!(!gate.lock().is_closed());
909        }
910
911        connection.frame().await;
912    }
913
914    fn book_value(message: AxDataWsMessage) -> serde_json::Value {
915        match message {
916            AxDataWsMessage::MdMessage(AxMdMessage::BookL2(book)) => {
917                serde_json::to_value(book).unwrap()
918            }
919            AxDataWsMessage::MdMessage(AxMdMessage::BookL3(book)) => {
920                serde_json::to_value(book).unwrap()
921            }
922            other => panic!("Expected book snapshot, received {other:?}"),
923        }
924    }
925
926    #[rstest]
927    #[case(false)]
928    #[case(true)]
929    #[tokio::test]
930    async fn test_canceled_queued_book_sends_nothing(#[case] cancel_before_queue: bool) {
931        let mut connection = HandlerConnection::new().await;
932        let cancel = CancellationToken::new();
933        if cancel_before_queue {
934            cancel.cancel();
935        }
936
937        let (command, gate, result) = book_command(cancel.clone());
938        connection.handler.handle_command(command).await;
939        cancel.cancel();
940        connection.frame().await;
941
942        assert!(matches!(
943            tokio::time::timeout(Duration::from_secs(2), result).await.unwrap().unwrap(),
944            Err(AxWsClientError::ClientError(message)) if message == "Book write canceled"
945        ));
946        assert_eq!(
947            connection.written.try_recv(),
948            Err(tokio::sync::mpsc::error::TryRecvError::Empty)
949        );
950        assert!(gate.lock().is_closed());
951        assert!(connection.handler.pending_subscription_requests.is_empty());
952    }
953
954    #[rstest]
955    #[tokio::test]
956    async fn test_held_book_write_allows_frames_and_turnover() {
957        let mut connection = HandlerConnection::new().await;
958        let client = connection.handler.inner.clone().unwrap();
959        client
960            .connection_mode_atomic()
961            .store(ConnectionMode::Reconnect.as_u8(), Ordering::Release);
962        let cancel = CancellationToken::new();
963        let (command, gate, result) = book_command(cancel.clone());
964        connection.handler.handle_command(command).await;
965        assert!(poll!(Box::pin(connection.handler.next())).is_pending());
966        connection.frame().await;
967        assert_eq!(
968            connection.written.try_recv(),
969            Err(tokio::sync::mpsc::error::TryRecvError::Empty)
970        );
971        assert!(gate.lock().is_closed());
972
973        cancel.cancel();
974        connection
975            .commands
976            .send(HandlerCommand::Unsubscribe {
977                request_id: 13,
978                symbol: Ustr::from("EURUSD-PERP"),
979                topic: TOPIC.to_string(),
980            })
981            .unwrap();
982
983        connection
984            .commands
985            .send(HandlerCommand::Subscribe {
986                request_id: 14,
987                symbol: Ustr::from("EURUSD-PERP"),
988                spec: AxMdSubscriptionSpec::new(AxMarketDataLevel::Level1, Some(true), Some(false)),
989            })
990            .unwrap();
991
992        connection.frame().await;
993        assert!(matches!(
994            tokio::time::timeout(Duration::from_secs(2), result).await.unwrap().unwrap(),
995            Err(AxWsClientError::ClientError(message)) if message == "Book write canceled"
996        ));
997
998        client
999            .connection_mode_atomic()
1000            .store(ConnectionMode::Active.as_u8(), Ordering::Release);
1001
1002        let expected = [
1003            serde_json::to_value(AxMdUnsubscribe {
1004                rid: 13,
1005                msg_type: AxMdRequestType::Unsubscribe,
1006                symbol: Ustr::from("EURUSD-PERP"),
1007            })
1008            .unwrap(),
1009            serde_json::to_value(AxMdSubscribe {
1010                rid: 14,
1011                msg_type: AxMdRequestType::Subscribe,
1012                symbol: Ustr::from("EURUSD-PERP"),
1013                level: AxMarketDataLevel::Level1,
1014                trades: Some(true),
1015                ticker: Some(false),
1016            })
1017            .unwrap(),
1018        ];
1019
1020        let writes = async {
1021            let mut writes = Vec::new();
1022            for _ in 0..expected.len() {
1023                writes.push(connection.written.recv().await.unwrap());
1024            }
1025
1026            writes
1027        };
1028
1029        let writes = tokio::select! {
1030            frame = connection.handler.next() => panic!("Unexpected frame: {frame:?}"),
1031            writes = tokio::time::timeout(Duration::from_secs(2), writes) => writes.unwrap(),
1032        };
1033
1034        assert_eq!(writes, expected);
1035        assert!(gate.lock().is_closed());
1036        assert_eq!(
1037            connection.written.try_recv(),
1038            Err(tokio::sync::mpsc::error::TryRecvError::Empty)
1039        );
1040    }
1041
1042    #[rstest]
1043    #[tokio::test]
1044    async fn test_held_book_write_allows_shutdown() {
1045        let mut connection = HandlerConnection::new().await;
1046        connection
1047            .handler
1048            .inner
1049            .as_ref()
1050            .unwrap()
1051            .connection_mode_atomic()
1052            .store(ConnectionMode::Reconnect.as_u8(), Ordering::Release);
1053        let (command, gate, result) = book_command(CancellationToken::new());
1054        connection.handler.handle_command(command).await;
1055        assert!(poll!(Box::pin(connection.handler.next())).is_pending());
1056        connection
1057            .commands
1058            .send(HandlerCommand::Disconnect)
1059            .unwrap();
1060        connection.frame().await;
1061
1062        assert!(result.await.is_err());
1063        assert!(gate.lock().is_closed());
1064        assert_eq!(
1065            connection.written.try_recv(),
1066            Err(tokio::sync::mpsc::error::TryRecvError::Disconnected)
1067        );
1068    }
1069
1070    #[rstest]
1071    #[tokio::test]
1072    async fn test_canceled_replacement_skips_subscribe_after_unsubscribe() {
1073        let mut connection = HandlerConnection::new().await;
1074        let cancel = CancellationToken::new();
1075        let (command, gate, result) = book_command(cancel.clone());
1076        connection.handler.handle_command(command).await;
1077        assert!(poll!(Box::pin(connection.handler.next())).is_pending());
1078        let unsubscribe = tokio::time::timeout(Duration::from_secs(2), connection.written.recv())
1079            .await
1080            .unwrap()
1081            .unwrap();
1082        cancel.cancel();
1083        connection.frame().await;
1084
1085        assert_eq!(
1086            unsubscribe,
1087            serde_json::to_value(AxMdUnsubscribe {
1088                rid: 12,
1089                msg_type: AxMdRequestType::Unsubscribe,
1090                symbol: Ustr::from("EURUSD-PERP"),
1091            })
1092            .unwrap()
1093        );
1094        assert!(matches!(
1095            tokio::time::timeout(Duration::from_secs(2), result).await.unwrap().unwrap(),
1096            Err(AxWsClientError::ClientError(message)) if message == "Book write canceled"
1097        ));
1098        assert!(gate.lock().is_closed());
1099        assert_eq!(
1100            connection.written.try_recv(),
1101            Err(tokio::sync::mpsc::error::TryRecvError::Empty)
1102        );
1103    }
1104
1105    #[rstest]
1106    #[tokio::test]
1107    async fn test_reconnected_book_write_keeps_gate_closed() {
1108        let mut connection = HandlerConnection::new().await;
1109        let client = connection.handler.inner.clone().unwrap();
1110        client
1111            .connection_mode_atomic()
1112            .store(ConnectionMode::Reconnect.as_u8(), Ordering::Release);
1113        let (command, gate, result) = book_command(CancellationToken::new());
1114        connection.handler.handle_command(command).await;
1115        assert!(poll!(Box::pin(connection.handler.next())).is_pending());
1116        client
1117            .connection_epoch_atomic()
1118            .fetch_add(1, Ordering::AcqRel);
1119        client
1120            .connection_mode_atomic()
1121            .store(ConnectionMode::Active.as_u8(), Ordering::Release);
1122        let result = tokio::select! {
1123            frame = connection.handler.next() => panic!("Unexpected frame: {frame:?}"),
1124            result = tokio::time::timeout(Duration::from_secs(2), result) => result.unwrap().unwrap(),
1125        };
1126
1127        assert!(matches!(
1128            result,
1129            Err(AxWsClientError::Transport(message)) if message == "send failed: connection changed before write"
1130        ));
1131        assert!(gate.lock().is_closed());
1132        assert_eq!(
1133            connection.written.try_recv(),
1134            Err(tokio::sync::mpsc::error::TryRecvError::Empty)
1135        );
1136        assert!(connection.handler.pending_subscription_requests.is_empty());
1137    }
1138
1139    #[rstest]
1140    #[tokio::test]
1141    async fn test_book_write_preserves_flags_and_opens_gate() {
1142        let mut connection = HandlerConnection::new().await;
1143        let (command, gate, result) = book_command(CancellationToken::new());
1144        connection.handler.handle_command(command).await;
1145        assert!(gate.lock().is_closed());
1146        assert_eq!(
1147            connection.written.try_recv(),
1148            Err(tokio::sync::mpsc::error::TryRecvError::Empty)
1149        );
1150        let result = tokio::select! {
1151            frame = connection.handler.next() => panic!("Unexpected frame: {frame:?}"),
1152            result = tokio::time::timeout(Duration::from_secs(2), result) => result.unwrap().unwrap(),
1153        };
1154        let first = connection.written.recv().await.unwrap();
1155        let second = connection.written.recv().await.unwrap();
1156
1157        assert!(result.is_ok());
1158        assert!(!gate.lock().is_closed());
1159        assert_eq!(
1160            first,
1161            serde_json::to_value(AxMdUnsubscribe {
1162                rid: 12,
1163                msg_type: AxMdRequestType::Unsubscribe,
1164                symbol: Ustr::from("EURUSD-PERP"),
1165            })
1166            .unwrap()
1167        );
1168        assert_eq!(
1169            second,
1170            serde_json::to_value(AxMdSubscribe {
1171                rid: 11,
1172                msg_type: AxMdRequestType::Subscribe,
1173                symbol: Ustr::from("EURUSD-PERP"),
1174                level: AxMarketDataLevel::Level2,
1175                trades: Some(false),
1176                ticker: Some(true),
1177            })
1178            .unwrap()
1179        );
1180    }
1181
1182    fn book_command(
1183        cancel: CancellationToken,
1184    ) -> (
1185        HandlerCommand,
1186        SnapshotGate,
1187        tokio::sync::oneshot::Receiver<Result<(), AxWsClientError>>,
1188    ) {
1189        let gate = SnapshotGate::default();
1190        gate.lock().close();
1191        let (completion, result) = tokio::sync::oneshot::channel();
1192
1193        let command = HandlerCommand::WriteBook {
1194            request_id: 11,
1195            unsubscribe_request_id: Some(12),
1196            symbol: Ustr::from("EURUSD-PERP"),
1197            spec: AxMdSubscriptionSpec::new(AxMarketDataLevel::Level2, Some(false), Some(true)),
1198            cancel,
1199            gate: gate.clone(),
1200            completion,
1201        };
1202
1203        (command, gate, result)
1204    }
1205
1206    struct HandlerConnection {
1207        handler: AxMdWsFeedHandler,
1208        commands: tokio::sync::mpsc::UnboundedSender<HandlerCommand>,
1209        frames: tokio::sync::mpsc::UnboundedSender<Message>,
1210        written: tokio::sync::mpsc::UnboundedReceiver<serde_json::Value>,
1211        server: tokio::task::JoinHandle<()>,
1212    }
1213
1214    impl HandlerConnection {
1215        async fn new() -> Self {
1216            let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
1217            let url = format!("ws://{}", listener.local_addr().unwrap());
1218            let (sent, written) = tokio::sync::mpsc::unbounded_channel();
1219
1220            let server = tokio::spawn(async move {
1221                let (stream, _) = listener.accept().await.unwrap();
1222                let mut socket = tokio_tungstenite::accept_async(stream).await.unwrap();
1223                while let Some(Ok(message)) = socket.next().await {
1224                    if let Message::Text(text) = message {
1225                        sent.send(serde_json::from_str(&text).unwrap()).unwrap();
1226                    }
1227                }
1228            });
1229
1230            let config = WebSocketConfig::builder()
1231                .url(url)
1232                .backend(TransportBackend::Tungstenite)
1233                .build()
1234                .unwrap();
1235            let client = WebSocketClient::builder()
1236                .config(config)
1237                .message_handler(Arc::new(|_| {}))
1238                .connect()
1239                .await
1240                .unwrap();
1241            let (commands, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
1242            let (frames, raw_rx) = tokio::sync::mpsc::unbounded_channel();
1243
1244            let mut handler = AxMdWsFeedHandler::new(
1245                Arc::new(AtomicBool::new(false)),
1246                cmd_rx,
1247                raw_rx,
1248                SubscriptionState::new(':'),
1249            );
1250            handler
1251                .handle_command(HandlerCommand::SetClient(client))
1252                .await;
1253
1254            Self {
1255                handler,
1256                commands,
1257                frames,
1258                written,
1259                server,
1260            }
1261        }
1262
1263        async fn frame(&mut self) {
1264            let heartbeat = include_str!("../../../test_data/ws_md_heartbeat.json");
1265            self.frames.send(Message::Text(heartbeat.into())).unwrap();
1266            let frame = tokio::time::timeout(Duration::from_secs(2), self.handler.next())
1267                .await
1268                .expect("handler must process frames while a book write waits")
1269                .unwrap();
1270
1271            let AxDataWsMessage::MdMessage(AxMdMessage::Heartbeat(heartbeat)) = frame else {
1272                panic!("Expected heartbeat, received {frame:?}");
1273            };
1274
1275            assert_eq!(heartbeat.ts, 1609459200);
1276            assert_eq!(heartbeat.tn, 123456789);
1277        }
1278    }
1279
1280    impl Drop for HandlerConnection {
1281        fn drop(&mut self) {
1282            self.server.abort();
1283        }
1284    }
1285
1286    fn create_handler(subscriptions: SubscriptionState) -> AxMdWsFeedHandler {
1287        let (_cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
1288        let (_raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
1289
1290        AxMdWsFeedHandler::new(
1291            Arc::new(AtomicBool::new(false)),
1292            cmd_rx,
1293            raw_rx,
1294            subscriptions,
1295        )
1296    }
1297}