Skip to main content

nautilus_architect_ax/websocket/data/
client.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 client for Ax.
17
18use std::{
19    fmt::{Debug, Display},
20    num::NonZeroU32,
21    sync::{
22        Arc,
23        atomic::{AtomicBool, AtomicI64, AtomicU8, Ordering},
24    },
25    time::Duration,
26};
27
28use ahash::AHashSet;
29use arc_swap::ArcSwap;
30use nautilus_core::{AtomicMap, string::secret::SecretString};
31use nautilus_live::{
32    SocketControl,
33    book::snapshot::SnapshotGate,
34    task::{SharedTaskSlot, TaskJoinOutcome},
35};
36use nautilus_network::{
37    ConnectionUrl,
38    http::create_standard_nautilus_headers,
39    mode::ConnectionMode,
40    websocket::{
41        InitialConnectRetryPolicy, PingHandler, ReconnectHeaders, SubscriptionState,
42        TransportBackend, WebSocketClient, WebSocketConfig, channel_message_handler,
43    },
44};
45use parking_lot::Mutex;
46use tokio_util::sync::CancellationToken;
47use ustr::Ustr;
48
49use super::{
50    AxMdSubscriptionSpec,
51    handler::{AxMdWsFeedHandler, HandlerCommand},
52};
53use crate::{
54    common::enums::{AxCandleWidth, AxMarketDataLevel},
55    websocket::messages::AxDataWsMessage,
56};
57
58/// Subscription topic delimiter for Ax.
59const AX_TOPIC_DELIMITER: char = ':';
60
61/// Result type for Ax WebSocket operations.
62pub type AxWsResult<T> = Result<T, AxWsClientError>;
63
64/// Error type for the Ax WebSocket client.
65#[derive(Debug, Clone)]
66pub enum AxWsClientError {
67    /// Transport/connection error.
68    Transport(String),
69    /// Channel send error.
70    ChannelError(String),
71    /// Client request error, such as a book that is no longer subscribed.
72    ClientError(String),
73    /// Operation timeout, such as a book snapshot that did not arrive.
74    OperationTimeout { timeout_ms: u64 },
75    /// Book frame that could not be converted to a snapshot.
76    InvalidSnapshot(String),
77}
78
79impl Display for AxWsClientError {
80    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
81        match self {
82            Self::Transport(msg) => write!(f, "Transport error: {msg}"),
83            Self::ChannelError(msg) => write!(f, "Channel error: {msg}"),
84            Self::ClientError(msg) => write!(f, "Client error: {msg}"),
85            Self::OperationTimeout { timeout_ms } => {
86                write!(f, "Operation timed out after {timeout_ms}ms")
87            }
88            Self::InvalidSnapshot(msg) => write!(f, "Invalid book snapshot: {msg}"),
89        }
90    }
91}
92
93impl std::error::Error for AxWsClientError {}
94
95#[derive(Debug, Default, Clone)]
96pub struct SymbolDataTypes {
97    pub quotes: bool,
98    pub trades: bool,
99    pub mark_prices: bool,
100    pub instrument_status: bool,
101    pub book_level: Option<AxMarketDataLevel>,
102}
103
104impl SymbolDataTypes {
105    fn effective_subscription(&self) -> Option<AxMdSubscriptionSpec> {
106        let book_level = self.book_level.or({
107            if self.quotes || self.ticker() {
108                Some(AxMarketDataLevel::Level1)
109            } else {
110                None
111            }
112        });
113
114        if let Some(level) = book_level {
115            return Some(self.book_subscription(level));
116        }
117
118        if self.trades {
119            return Some(AxMdSubscriptionSpec::new(
120                AxMarketDataLevel::Trades,
121                None,
122                None,
123            ));
124        }
125
126        None
127    }
128
129    fn book_subscription(&self, level: AxMarketDataLevel) -> AxMdSubscriptionSpec {
130        AxMdSubscriptionSpec::new(level, Some(self.trades), Some(self.ticker()))
131    }
132
133    fn ticker(&self) -> bool {
134        self.mark_prices || self.instrument_status
135    }
136
137    fn is_empty(&self) -> bool {
138        !self.quotes
139            && !self.trades
140            && !self.mark_prices
141            && !self.instrument_status
142            && self.book_level.is_none()
143    }
144}
145
146/// Market data WebSocket client for Ax.
147///
148/// Provides streaming market data including tickers, trades, order books, and candles.
149/// Requires Bearer token authentication obtained via the HTTP `/api/authenticate` endpoint.
150pub struct AxMdWebSocketClient {
151    url: ConnectionUrl,
152    heartbeat: Option<u64>,
153    auth_token: Arc<Mutex<Option<SecretString>>>,
154    reconnect_headers: Arc<Mutex<Option<ReconnectHeaders>>>,
155    connection_mode: Arc<ArcSwap<AtomicU8>>,
156    cmd_tx: Arc<tokio::sync::RwLock<tokio::sync::mpsc::UnboundedSender<HandlerCommand>>>,
157    out_rx: Option<Arc<tokio::sync::mpsc::UnboundedReceiver<AxDataWsMessage>>>,
158    signal: Arc<AtomicBool>,
159    cancellation_token: Arc<ArcSwap<CancellationToken>>,
160    task_handle: Arc<SharedTaskSlot<()>>,
161    connect_lock: Arc<tokio::sync::Mutex<()>>,
162    subscriptions: SubscriptionState,
163    request_id_counter: Arc<AtomicI64>,
164    subscribe_lock: Arc<tokio::sync::Mutex<()>>,
165    symbol_data_types: Arc<AtomicMap<String, SymbolDataTypes>>,
166    status_invalidations: Arc<Mutex<AHashSet<Ustr>>>,
167    transport_backend: TransportBackend,
168    proxy_url: Option<SecretString>,
169    socket_control: Option<SocketControl>,
170}
171
172impl Debug for AxMdWebSocketClient {
173    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
174        f.debug_struct(stringify!(AxMdWebSocketClient))
175            .field("url", &self.url)
176            .field("heartbeat", &self.heartbeat)
177            .field("confirmed_subscriptions", &self.subscriptions.len())
178            .finish()
179    }
180}
181
182impl Clone for AxMdWebSocketClient {
183    fn clone(&self) -> Self {
184        Self {
185            url: self.url.clone(),
186            heartbeat: self.heartbeat,
187            auth_token: Arc::clone(&self.auth_token),
188            reconnect_headers: Arc::clone(&self.reconnect_headers),
189            connection_mode: Arc::clone(&self.connection_mode),
190            cmd_tx: Arc::clone(&self.cmd_tx),
191            out_rx: None,
192            signal: Arc::clone(&self.signal),
193            cancellation_token: Arc::clone(&self.cancellation_token),
194            task_handle: Arc::clone(&self.task_handle),
195            connect_lock: Arc::clone(&self.connect_lock),
196            subscriptions: self.subscriptions.clone(),
197            subscribe_lock: Arc::clone(&self.subscribe_lock),
198            request_id_counter: Arc::clone(&self.request_id_counter),
199            symbol_data_types: Arc::clone(&self.symbol_data_types),
200            status_invalidations: Arc::clone(&self.status_invalidations),
201            transport_backend: self.transport_backend,
202            proxy_url: self.proxy_url.clone(),
203            socket_control: self.socket_control.clone(),
204        }
205    }
206}
207
208impl AxMdWebSocketClient {
209    fn initial_connect_retry_policy() -> InitialConnectRetryPolicy {
210        InitialConnectRetryPolicy {
211            max_attempts: NonZeroU32::new(5).expect("initial connect attempts must be non-zero"),
212            delay_initial: Duration::from_millis(500),
213            delay_max: Duration::from_secs(5),
214            backoff_factor: 2.0,
215            jitter_ms: 250,
216        }
217    }
218
219    /// Creates a new Ax market data WebSocket client.
220    ///
221    /// The `auth_token` is a Bearer token obtained from the HTTP `/api/authenticate` endpoint.
222    #[must_use]
223    pub fn new(
224        url: String,
225        auth_token: impl Into<SecretString>,
226        heartbeat: u64,
227        transport_backend: TransportBackend,
228        proxy_url: Option<String>,
229    ) -> Self {
230        let (cmd_tx, _cmd_rx) = tokio::sync::mpsc::unbounded_channel::<HandlerCommand>();
231
232        let initial_mode = AtomicU8::new(ConnectionMode::Closed.as_u8());
233        let connection_mode = Arc::new(ArcSwap::from_pointee(initial_mode));
234
235        Self {
236            url: url.into(),
237            heartbeat: Some(heartbeat),
238            auth_token: Arc::new(Mutex::new(Some(auth_token.into()))),
239            reconnect_headers: Arc::new(Mutex::new(None)),
240            connection_mode,
241            cmd_tx: Arc::new(tokio::sync::RwLock::new(cmd_tx)),
242            out_rx: None,
243            signal: Arc::new(AtomicBool::new(false)),
244            cancellation_token: Arc::new(ArcSwap::from_pointee(CancellationToken::new())),
245            task_handle: Arc::new(SharedTaskSlot::new()),
246            connect_lock: Arc::new(tokio::sync::Mutex::new(())),
247            subscriptions: SubscriptionState::new(AX_TOPIC_DELIMITER),
248            request_id_counter: Arc::new(AtomicI64::new(1)),
249            subscribe_lock: Arc::new(tokio::sync::Mutex::new(())),
250            symbol_data_types: Arc::new(AtomicMap::new()),
251            status_invalidations: Arc::new(Mutex::new(AHashSet::new())),
252            transport_backend,
253            proxy_url: proxy_url.map(SecretString::from),
254            socket_control: None,
255        }
256    }
257
258    /// Creates a new Ax market data WebSocket client without authentication.
259    ///
260    /// Use [`set_auth_token`](Self::set_auth_token) to set the token before connecting.
261    #[must_use]
262    pub fn without_auth(
263        url: String,
264        heartbeat: u64,
265        transport_backend: TransportBackend,
266        proxy_url: Option<String>,
267    ) -> Self {
268        let (cmd_tx, _cmd_rx) = tokio::sync::mpsc::unbounded_channel::<HandlerCommand>();
269
270        let initial_mode = AtomicU8::new(ConnectionMode::Closed.as_u8());
271        let connection_mode = Arc::new(ArcSwap::from_pointee(initial_mode));
272
273        Self {
274            url: url.into(),
275            heartbeat: Some(heartbeat),
276            auth_token: Arc::new(Mutex::new(None)),
277            reconnect_headers: Arc::new(Mutex::new(None)),
278            connection_mode,
279            cmd_tx: Arc::new(tokio::sync::RwLock::new(cmd_tx)),
280            out_rx: None,
281            signal: Arc::new(AtomicBool::new(false)),
282            cancellation_token: Arc::new(ArcSwap::from_pointee(CancellationToken::new())),
283            task_handle: Arc::new(SharedTaskSlot::new()),
284            connect_lock: Arc::new(tokio::sync::Mutex::new(())),
285            subscriptions: SubscriptionState::new(AX_TOPIC_DELIMITER),
286            request_id_counter: Arc::new(AtomicI64::new(1)),
287            subscribe_lock: Arc::new(tokio::sync::Mutex::new(())),
288            symbol_data_types: Arc::new(AtomicMap::new()),
289            status_invalidations: Arc::new(Mutex::new(AHashSet::new())),
290            transport_backend,
291            proxy_url: proxy_url.map(SecretString::from),
292            socket_control: None,
293        }
294    }
295
296    /// Configures socket state reporting and reconnect control.
297    #[must_use]
298    pub fn with_socket_control(mut self, control: SocketControl) -> Self {
299        self.socket_control = Some(control);
300        self
301    }
302
303    /// Returns the WebSocket URL.
304    #[must_use]
305    pub fn url(&self) -> &str {
306        self.url.expose()
307    }
308
309    /// Sets the authentication token for subsequent connections.
310    ///
311    /// This should be called before `connect()` if authentication is required.
312    pub fn set_auth_token(&self, token: impl Into<SecretString>) {
313        *self.auth_token.lock() = Some(token.into());
314    }
315
316    /// Updates the token used by future automatic reconnect attempts.
317    ///
318    /// Updating the token does not interrupt the active WebSocket connection.
319    ///
320    /// # Errors
321    ///
322    /// Returns an error if the reconnect header cannot be updated.
323    pub fn update_auth_token(&self, token: SecretString) -> AxWsResult<()> {
324        let value = format!("Bearer {}", token.expose_secret());
325
326        if let Some(headers) = self.reconnect_headers.lock().as_ref() {
327            headers
328                .update("Authorization", &value)
329                .map_err(|e| AxWsClientError::Transport(e.to_string()))?;
330        }
331        self.set_auth_token(token);
332        Ok(())
333    }
334
335    /// Returns whether the client is currently connected and active.
336    #[must_use]
337    pub fn is_active(&self) -> bool {
338        let connection_mode_arc = self.connection_mode.load();
339        ConnectionMode::from_atomic(&connection_mode_arc).is_active()
340            && !self.signal.load(Ordering::Acquire)
341    }
342
343    /// Returns whether the client is closed.
344    #[must_use]
345    pub fn is_closed(&self) -> bool {
346        let connection_mode_arc = self.connection_mode.load();
347        ConnectionMode::from_atomic(&connection_mode_arc).is_closed()
348            || self.signal.load(Ordering::Acquire)
349    }
350
351    /// Returns the number of confirmed subscriptions.
352    #[must_use]
353    pub fn subscription_count(&self) -> usize {
354        self.subscriptions.len()
355    }
356
357    /// Returns the symbol data types map (shared with handler).
358    #[must_use]
359    pub fn symbol_data_types(&self) -> Arc<AtomicMap<String, SymbolDataTypes>> {
360        Arc::clone(&self.symbol_data_types)
361    }
362
363    /// Returns the shared set of symbols whose instrument status cache has been invalidated.
364    pub fn status_invalidations(&self) -> Arc<Mutex<AHashSet<Ustr>>> {
365        Arc::clone(&self.status_invalidations)
366    }
367
368    fn next_request_id(&self) -> i64 {
369        self.request_id_counter.fetch_add(1, Ordering::Relaxed)
370    }
371
372    fn is_subscribed_topic(&self, topic: &str) -> bool {
373        let (channel, symbol) = topic
374            .split_once(AX_TOPIC_DELIMITER)
375            .map_or((topic, None), |(c, s)| (c, Some(s)));
376        let channel_ustr = Ustr::from(channel);
377        let symbol_ustr = symbol.map_or_else(|| Ustr::from(""), Ustr::from);
378        self.subscriptions
379            .is_subscribed(&channel_ustr, &symbol_ustr)
380    }
381
382    /// Establishes the WebSocket connection.
383    ///
384    /// # Errors
385    ///
386    /// Returns an error if the connection cannot be established or the initial handler command
387    /// cannot be sent.
388    pub async fn connect(&mut self) -> AxWsResult<()> {
389        let connect_lock = Arc::clone(&self.connect_lock);
390        let _guard = connect_lock.lock().await;
391
392        if !self.task_handle.is_empty() && !self.task_handle.is_finished() {
393            return Err(AxWsClientError::Transport(
394                "WebSocket handler is already running".to_string(),
395            ));
396        }
397
398        if let Some(outcome) = self
399            .task_handle
400            .finish(Duration::from_secs(2), Duration::from_secs(2))
401            .await
402        {
403            match outcome {
404                TaskJoinOutcome::Completed(()) | TaskJoinOutcome::Aborted => {}
405                TaskJoinOutcome::Failed(error) => {
406                    return Err(AxWsClientError::Transport(format!(
407                        "Previous WebSocket handler failed: {error}"
408                    )));
409                }
410                TaskJoinOutcome::Incomplete => {
411                    return Err(AxWsClientError::Transport(
412                        "Previous WebSocket handler did not stop within shutdown bounds"
413                            .to_string(),
414                    ));
415                }
416            }
417        }
418
419        self.signal.store(false, Ordering::Release);
420        let cancellation_token = CancellationToken::new();
421        self.cancellation_token
422            .store(Arc::new(cancellation_token.clone()));
423
424        let (raw_handler, raw_rx) = channel_message_handler();
425
426        // No-op: ping responses are handled internally by the WebSocketClient
427        let ping_handler: PingHandler = Arc::new(move |_payload: Vec<u8>| {});
428
429        let mut headers = create_standard_nautilus_headers();
430
431        let auth_token = self.auth_token.lock().clone();
432
433        if let Some(token) = auth_token {
434            headers.push((
435                "Authorization".to_string(),
436                format!("Bearer {}", token.expose_secret()),
437            ));
438        }
439
440        let config = WebSocketConfig {
441            url: self.url.expose().to_owned(),
442            headers,
443            heartbeat_interval_secs: self.heartbeat,
444            heartbeat_payload: None, // Ax server sends heartbeats
445            connect_timeout_ms: Some(5_000),
446            reconnect_delay_initial_ms: Some(500),
447            reconnect_delay_max_ms: Some(5_000),
448            reconnect_backoff_factor: Some(1.5),
449            reconnect_jitter_ms: Some(250),
450            reconnect_max_attempts: None,
451            heartbeat_timeout_secs: None,
452            idle_timeout_ms: None,
453            writer_capacity: None,
454            backend: self.transport_backend,
455            proxy_url: self
456                .proxy_url
457                .as_ref()
458                .map(|url| url.expose_secret().to_owned()),
459            max_message_size_bytes: None,
460            max_frame_size_bytes: None,
461        };
462
463        let client = WebSocketClient::builder()
464            .config(config.clone())
465            .message_handler(raw_handler.clone())
466            .ping_handler(ping_handler.clone())
467            .initial_connect_retry_policy(Self::initial_connect_retry_policy())
468            .cancellation_token(cancellation_token)
469            .maybe_state_sink(self.socket_control.as_ref().map(SocketControl::sink))
470            .connect()
471            .await
472            .map_err(|e| {
473                AxWsClientError::Transport(format!(
474                    "WebSocket connection failed: {}: {}",
475                    self.url.origin(),
476                    e.redacted_message()
477                ))
478            })?;
479
480        let connection_mode = client.connection_mode_atomic();
481        let reconnect_handle = client.reconnect_handle();
482        *self.reconnect_headers.lock() = Some(client.reconnect_headers());
483
484        let (out_tx, out_rx) = tokio::sync::mpsc::unbounded_channel::<AxDataWsMessage>();
485        self.out_rx = Some(Arc::new(out_rx));
486
487        let (cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel::<HandlerCommand>();
488        cmd_tx
489            .send(HandlerCommand::SetClient(client))
490            .map_err(|e| AxWsClientError::ChannelError(e.to_string()))?;
491
492        if !self.subscriptions.all_topics().is_empty() {
493            cmd_tx
494                .send(HandlerCommand::ReplaySubscriptions)
495                .map_err(|e| AxWsClientError::ChannelError(e.to_string()))?;
496        }
497
498        {
499            let mut command_sender = self.cmd_tx.write().await;
500            *command_sender = cmd_tx.clone();
501            self.connection_mode.store(connection_mode);
502        }
503
504        let signal = Arc::clone(&self.signal);
505        let subscriptions = self.subscriptions.clone();
506
507        if let Err(e) = self.task_handle.spawn(async move {
508            let mut handler =
509                AxMdWsFeedHandler::new(signal.clone(), cmd_rx, raw_rx, subscriptions.clone());
510
511            while let Some(msg) = handler.next().await {
512                if matches!(msg, AxDataWsMessage::Reconnected) {
513                    log::info!("WebSocket reconnected, subscriptions will be replayed");
514                }
515
516                if out_tx.send(msg).is_err() {
517                    log::debug!("Output channel closed");
518                    break;
519                }
520            }
521
522            log::debug!("Handler loop exited");
523        }) {
524            self.out_rx = None;
525            return Err(AxWsClientError::Transport(format!(
526                "Failed to start WebSocket handler task: {e}"
527            )));
528        }
529
530        if let Some(control) = &self.socket_control {
531            control.register(move || reconnect_handle.request_reconnect());
532        }
533
534        Ok(())
535    }
536
537    /// Subscribes to order book deltas for a symbol.
538    ///
539    /// Uses reference counting so the underlying AX subscription is only
540    /// removed when all data types have been unsubscribed.
541    ///
542    /// # Errors
543    ///
544    /// Returns an error if the subscription command cannot be sent.
545    pub async fn subscribe_book_deltas(
546        &self,
547        symbol: &str,
548        level: AxMarketDataLevel,
549    ) -> AxWsResult<()> {
550        let _guard = self.subscribe_lock.lock().await;
551
552        let current = self
553            .symbol_data_types
554            .load()
555            .get(symbol)
556            .cloned()
557            .unwrap_or_default();
558
559        if current.book_level == Some(level) {
560            log::debug!("Book deltas already subscribed for {symbol} at {level:?}, skipping");
561            return Ok(());
562        }
563
564        let old_spec = current.effective_subscription();
565        let mut next = current.clone();
566        next.book_level = Some(level);
567        let new_spec = next.effective_subscription();
568
569        self.update_data_subscription(symbol, old_spec, new_spec)
570            .await?;
571
572        self.symbol_data_types.rcu(|m| {
573            let entry = m.entry(symbol.to_string()).or_default();
574            entry.book_level = Some(level);
575        });
576
577        Ok(())
578    }
579
580    /// Subscribes to order book deltas for a symbol, opening `gate` once the subscription is
581    /// written.
582    ///
583    /// A stream already open with the same options is replaced so the book starts from a fresh
584    /// snapshot. Returns without subscribing when `cancel` has already fired, and stops waiting
585    /// once it fires. Cancellation skips the book write's unsent work; a write already admitted to the
586    /// network can still complete before later subscription changes.
587    pub(crate) async fn subscribe_book_deltas_gated(
588        &self,
589        symbol: Ustr,
590        level: AxMarketDataLevel,
591        cancel: CancellationToken,
592        gate: SnapshotGate,
593    ) -> AxWsResult<()> {
594        let (completion, receiver) = tokio::sync::oneshot::channel();
595
596        {
597            let _guard = self.subscribe_lock.lock().await;
598
599            if cancel.is_cancelled() {
600                return Ok(());
601            }
602
603            let current = self
604                .symbol_data_types
605                .load()
606                .get(symbol.as_str())
607                .cloned()
608                .unwrap_or_default();
609            let old_spec = current.effective_subscription();
610            let spec = current.book_subscription(level);
611            let replace = old_spec == Some(spec);
612
613            if let Some(old) = old_spec.filter(|_| !replace) {
614                log::debug!("Resubscribing {symbol}: {old:?} -> {spec:?}");
615                self.send_unsubscribe(symbol.as_str(), old).await?;
616            }
617
618            let topic = spec.topic(symbol.as_str());
619
620            if !replace {
621                self.subscriptions.mark_subscribe(&topic);
622            }
623
624            let command = HandlerCommand::WriteBook {
625                request_id: self.next_request_id(),
626                unsubscribe_request_id: replace.then(|| self.next_request_id()),
627                symbol,
628                spec,
629                cancel: cancel.clone(),
630                gate,
631                completion,
632            };
633
634            if let Err(e) = self.send_cmd(command).await {
635                if !replace {
636                    self.subscriptions.mark_unsubscribe(&topic);
637                }
638
639                return Err(e);
640            }
641
642            self.symbol_data_types.rcu(|m| {
643                m.entry(symbol.to_string()).or_default().book_level = Some(level);
644            });
645        }
646
647        tokio::select! {
648            biased;
649            () = cancel.cancelled() => Ok(()),
650            // The handler stopped after taking the command, so the subscription stays desired
651            result = receiver => result.map_err(|e| AxWsClientError::Transport(e.to_string()))?,
652        }
653    }
654
655    /// Replaces the symbol's market data subscription to request a fresh book snapshot, opening
656    /// `gate` once the subscription is written.
657    ///
658    /// Echoes the symbol's current subscription options and keeps the subscription desired for
659    /// reconnect replay.
660    pub(crate) async fn resubscribe_book_gated(
661        &self,
662        symbol: Ustr,
663        cancel: CancellationToken,
664        gate: SnapshotGate,
665    ) -> AxWsResult<()> {
666        let (completion, receiver) = tokio::sync::oneshot::channel();
667
668        {
669            // Serializes the subscription lookup with subscribe and unsubscribe changes
670            let _guard = self.subscribe_lock.lock().await;
671
672            if cancel.is_cancelled() {
673                return Err(AxWsClientError::ClientError(
674                    "Book recovery canceled".to_string(),
675                ));
676            }
677
678            let Some(spec) = self
679                .symbol_data_types
680                .load()
681                .get(symbol.as_str())
682                .and_then(|types| types.book_level.map(|level| types.book_subscription(level)))
683            else {
684                return Err(AxWsClientError::ClientError(format!(
685                    "Book deltas for {symbol} are no longer subscribed"
686                )));
687            };
688
689            self.send_cmd(HandlerCommand::WriteBook {
690                request_id: self.next_request_id(),
691                unsubscribe_request_id: Some(self.next_request_id()),
692                symbol,
693                spec,
694                cancel,
695                gate,
696                completion,
697            })
698            .await?;
699        }
700
701        receiver
702            .await
703            .map_err(|e| AxWsClientError::Transport(e.to_string()))?
704    }
705
706    /// Subscribes to quote data for a symbol.
707    ///
708    /// Uses reference counting so the underlying AX subscription is only
709    /// removed when all data types have been unsubscribed.
710    ///
711    /// # Errors
712    ///
713    /// Returns an error if the subscription command cannot be sent.
714    pub async fn subscribe_quotes(&self, symbol: &str) -> AxWsResult<()> {
715        let _guard = self.subscribe_lock.lock().await;
716
717        let current = self
718            .symbol_data_types
719            .load()
720            .get(symbol)
721            .cloned()
722            .unwrap_or_default();
723        let old_spec = current.effective_subscription();
724        let mut next = current.clone();
725        next.quotes = true;
726        let new_spec = next.effective_subscription();
727
728        self.update_data_subscription(symbol, old_spec, new_spec)
729            .await?;
730
731        self.symbol_data_types.rcu(|m| {
732            m.entry(symbol.to_string()).or_default().quotes = true;
733        });
734
735        Ok(())
736    }
737
738    /// Subscribes to trade data for a symbol.
739    ///
740    /// Uses reference counting so the underlying AX subscription is only
741    /// removed when all data types have been unsubscribed.
742    ///
743    /// # Errors
744    ///
745    /// Returns an error if the subscription command cannot be sent.
746    pub async fn subscribe_trades(&self, symbol: &str) -> AxWsResult<()> {
747        let _guard = self.subscribe_lock.lock().await;
748
749        let current = self
750            .symbol_data_types
751            .load()
752            .get(symbol)
753            .cloned()
754            .unwrap_or_default();
755        let old_spec = current.effective_subscription();
756        let mut next = current.clone();
757        next.trades = true;
758        let new_spec = next.effective_subscription();
759
760        self.update_data_subscription(symbol, old_spec, new_spec)
761            .await?;
762
763        self.symbol_data_types.rcu(|m| {
764            m.entry(symbol.to_string()).or_default().trades = true;
765        });
766
767        Ok(())
768    }
769
770    /// Unsubscribes from order book deltas for a symbol.
771    ///
772    /// The underlying AX subscription is only removed when all data types
773    /// (quotes, trades, book) have been unsubscribed.
774    ///
775    /// # Errors
776    ///
777    /// Returns an error if the unsubscribe command cannot be sent.
778    pub async fn unsubscribe_book_deltas(&self, symbol: &str) -> AxWsResult<()> {
779        let _guard = self.subscribe_lock.lock().await;
780
781        let Some(current) = self.symbol_data_types.load().get(symbol).cloned() else {
782            log::debug!("Symbol {symbol} not subscribed, skipping unsubscribe book deltas");
783            return Ok(());
784        };
785        let old_spec = current.effective_subscription();
786        let mut next = current.clone();
787        next.book_level = None;
788        let new_spec = next.effective_subscription();
789
790        self.update_data_subscription(symbol, old_spec, new_spec)
791            .await?;
792
793        self.symbol_data_types.rcu(|m| {
794            if let Some(entry) = m.get_mut(symbol) {
795                entry.book_level = None;
796                if entry.is_empty() {
797                    m.remove(symbol);
798                }
799            }
800        });
801
802        Ok(())
803    }
804
805    /// Unsubscribes from quote data for a symbol.
806    ///
807    /// The underlying AX subscription is only removed when all data types
808    /// (quotes, trades, book) have been unsubscribed.
809    ///
810    /// # Errors
811    ///
812    /// Returns an error if the unsubscribe command cannot be sent.
813    pub async fn unsubscribe_quotes(&self, symbol: &str) -> AxWsResult<()> {
814        let _guard = self.subscribe_lock.lock().await;
815
816        let Some(current) = self.symbol_data_types.load().get(symbol).cloned() else {
817            log::debug!("Symbol {symbol} not subscribed, skipping unsubscribe quotes");
818            return Ok(());
819        };
820        let old_spec = current.effective_subscription();
821        let mut next = current.clone();
822        next.quotes = false;
823        let new_spec = next.effective_subscription();
824
825        self.update_data_subscription(symbol, old_spec, new_spec)
826            .await?;
827
828        self.symbol_data_types.rcu(|m| {
829            if let Some(entry) = m.get_mut(symbol) {
830                entry.quotes = false;
831                if entry.is_empty() {
832                    m.remove(symbol);
833                }
834            }
835        });
836
837        Ok(())
838    }
839
840    /// Unsubscribes from trade data for a symbol.
841    ///
842    /// The underlying AX subscription is only removed when all data types
843    /// (quotes, trades, book) have been unsubscribed.
844    ///
845    /// # Errors
846    ///
847    /// Returns an error if the unsubscribe command cannot be sent.
848    pub async fn unsubscribe_trades(&self, symbol: &str) -> AxWsResult<()> {
849        let _guard = self.subscribe_lock.lock().await;
850
851        let Some(current) = self.symbol_data_types.load().get(symbol).cloned() else {
852            log::debug!("Symbol {symbol} not subscribed, skipping unsubscribe trades");
853            return Ok(());
854        };
855        let old_spec = current.effective_subscription();
856        let mut next = current.clone();
857        next.trades = false;
858        let new_spec = next.effective_subscription();
859
860        self.update_data_subscription(symbol, old_spec, new_spec)
861            .await?;
862
863        self.symbol_data_types.rcu(|m| {
864            if let Some(entry) = m.get_mut(symbol) {
865                entry.trades = false;
866                if entry.is_empty() {
867                    m.remove(symbol);
868                }
869            }
870        });
871
872        Ok(())
873    }
874
875    /// Subscribes to mark prices for a symbol.
876    ///
877    /// Ensures at least an L1 subscription so that ticker messages
878    /// (which carry the mark price field) are received.
879    ///
880    /// # Errors
881    ///
882    /// Returns an error if the subscription command cannot be sent.
883    pub async fn subscribe_mark_prices(&self, symbol: &str) -> AxWsResult<()> {
884        let _guard = self.subscribe_lock.lock().await;
885
886        let current = self
887            .symbol_data_types
888            .load()
889            .get(symbol)
890            .cloned()
891            .unwrap_or_default();
892        let old_spec = current.effective_subscription();
893        let mut next = current.clone();
894        next.mark_prices = true;
895        let new_spec = next.effective_subscription();
896
897        self.update_data_subscription(symbol, old_spec, new_spec)
898            .await?;
899
900        self.symbol_data_types.rcu(|m| {
901            m.entry(symbol.to_string()).or_default().mark_prices = true;
902        });
903
904        Ok(())
905    }
906
907    /// Unsubscribes from mark prices for a symbol.
908    ///
909    /// The underlying AX subscription is only removed when all data types
910    /// have been unsubscribed.
911    ///
912    /// # Errors
913    ///
914    /// Returns an error if the unsubscribe command cannot be sent.
915    pub async fn unsubscribe_mark_prices(&self, symbol: &str) -> AxWsResult<()> {
916        let _guard = self.subscribe_lock.lock().await;
917
918        let Some(current) = self.symbol_data_types.load().get(symbol).cloned() else {
919            log::debug!("Symbol {symbol} not subscribed, skipping unsubscribe mark prices");
920            return Ok(());
921        };
922        let old_spec = current.effective_subscription();
923        let mut next = current.clone();
924        next.mark_prices = false;
925        let new_spec = next.effective_subscription();
926
927        self.update_data_subscription(symbol, old_spec, new_spec)
928            .await?;
929
930        self.symbol_data_types.rcu(|m| {
931            if let Some(entry) = m.get_mut(symbol) {
932                entry.mark_prices = false;
933                if entry.is_empty() {
934                    m.remove(symbol);
935                }
936            }
937        });
938
939        Ok(())
940    }
941
942    /// Subscribes to instrument status for a symbol.
943    ///
944    /// Ensures at least an L1 subscription so that ticker messages
945    /// (which carry the instrument state field) are received.
946    ///
947    /// # Errors
948    ///
949    /// Returns an error if the subscription command cannot be sent.
950    pub async fn subscribe_instrument_status(&self, symbol: &str) -> AxWsResult<()> {
951        let _guard = self.subscribe_lock.lock().await;
952
953        let current = self
954            .symbol_data_types
955            .load()
956            .get(symbol)
957            .cloned()
958            .unwrap_or_default();
959        let old_spec = current.effective_subscription();
960        let mut next = current.clone();
961        next.instrument_status = true;
962        let new_spec = next.effective_subscription();
963
964        self.update_data_subscription(symbol, old_spec, new_spec)
965            .await?;
966
967        self.symbol_data_types.rcu(|m| {
968            m.entry(symbol.to_string()).or_default().instrument_status = true;
969        });
970
971        Ok(())
972    }
973
974    /// Unsubscribes from instrument status for a symbol.
975    ///
976    /// The underlying AX subscription is only removed when all data types
977    /// have been unsubscribed.
978    ///
979    /// # Errors
980    ///
981    /// Returns an error if the unsubscribe command cannot be sent.
982    pub async fn unsubscribe_instrument_status(&self, symbol: &str) -> AxWsResult<()> {
983        let _guard = self.subscribe_lock.lock().await;
984
985        let Some(current) = self.symbol_data_types.load().get(symbol).cloned() else {
986            log::debug!("Symbol {symbol} not subscribed, skipping unsubscribe instrument status");
987            return Ok(());
988        };
989        let old_spec = current.effective_subscription();
990        let mut next = current.clone();
991        next.instrument_status = false;
992        let new_spec = next.effective_subscription();
993
994        self.update_data_subscription(symbol, old_spec, new_spec)
995            .await?;
996
997        self.symbol_data_types.rcu(|m| {
998            if let Some(entry) = m.get_mut(symbol) {
999                entry.instrument_status = false;
1000                if entry.is_empty() {
1001                    m.remove(symbol);
1002                }
1003            }
1004        });
1005
1006        self.status_invalidations.lock().insert(Ustr::from(symbol));
1007
1008        Ok(())
1009    }
1010
1011    async fn update_data_subscription(
1012        &self,
1013        symbol: &str,
1014        old_spec: Option<AxMdSubscriptionSpec>,
1015        new_spec: Option<AxMdSubscriptionSpec>,
1016    ) -> AxWsResult<()> {
1017        if old_spec == new_spec {
1018            return Ok(());
1019        }
1020
1021        match (old_spec, new_spec) {
1022            (None, Some(spec)) => {
1023                log::debug!("Subscribing {symbol} at {spec:?}");
1024                self.send_subscribe(symbol, spec).await
1025            }
1026            (Some(old), None) => {
1027                log::debug!("Unsubscribing {symbol} (no remaining data types)");
1028                self.send_unsubscribe(symbol, old).await
1029            }
1030            (Some(old), Some(new)) => {
1031                log::debug!("Resubscribing {symbol}: {old:?} -> {new:?}");
1032                self.send_unsubscribe(symbol, old).await?;
1033                if let Err(e) = self.send_subscribe(symbol, new).await {
1034                    log::warn!("Resubscribe failed for {symbol} at {new:?}: {e}");
1035                    if let Err(restore_err) = self.send_subscribe(symbol, old).await {
1036                        log::error!(
1037                            "Failed to restore {symbol} at {old:?}: {restore_err}, \
1038                             reconnection required"
1039                        );
1040                        self.subscriptions.mark_subscribe(&old.topic(symbol));
1041                    }
1042                    return Err(e);
1043                }
1044                Ok(())
1045            }
1046            (None, None) => Ok(()),
1047        }
1048    }
1049
1050    async fn send_subscribe(&self, symbol: &str, spec: AxMdSubscriptionSpec) -> AxWsResult<()> {
1051        let topic = spec.topic(symbol);
1052        let request_id = self.next_request_id();
1053
1054        self.subscriptions.mark_subscribe(&topic);
1055
1056        if let Err(e) = self
1057            .send_cmd(HandlerCommand::Subscribe {
1058                request_id,
1059                symbol: Ustr::from(symbol),
1060                spec,
1061            })
1062            .await
1063        {
1064            self.subscriptions.mark_unsubscribe(&topic);
1065            return Err(e);
1066        }
1067
1068        Ok(())
1069    }
1070
1071    async fn send_unsubscribe(&self, symbol: &str, spec: AxMdSubscriptionSpec) -> AxWsResult<()> {
1072        let request_id = self.next_request_id();
1073        let topic = spec.topic(symbol);
1074        let was_pending = self
1075            .subscriptions
1076            .pending_subscribe_topics()
1077            .contains(&topic);
1078
1079        self.subscriptions.mark_unsubscribe(&topic);
1080
1081        if let Err(e) = self
1082            .send_cmd(HandlerCommand::Unsubscribe {
1083                request_id,
1084                symbol: Ustr::from(symbol),
1085                topic: topic.clone(),
1086            })
1087            .await
1088        {
1089            self.restore_unsubscribe_state(&topic, was_pending);
1090            return Err(e);
1091        }
1092
1093        Ok(())
1094    }
1095
1096    /// Subscribes to candle data for a symbol.
1097    ///
1098    /// Skips sending if already subscribed or subscription is pending.
1099    ///
1100    /// # Errors
1101    ///
1102    /// Returns an error if the subscription command cannot be sent.
1103    pub async fn subscribe_candles(&self, symbol: &str, width: AxCandleWidth) -> AxWsResult<()> {
1104        let _guard = self.subscribe_lock.lock().await;
1105        let topic = format!("candles:{symbol}:{width:?}");
1106
1107        // Skip if already subscribed or pending
1108        if self.is_subscribed_topic(&topic) {
1109            log::debug!("Already subscribed to {topic}, skipping");
1110            return Ok(());
1111        }
1112
1113        let request_id = self.next_request_id();
1114
1115        // Mark pending BEFORE sending to prevent race conditions with concurrent subscribes
1116        self.subscriptions.mark_subscribe(&topic);
1117
1118        if let Err(e) = self
1119            .send_cmd(HandlerCommand::SubscribeCandles {
1120                request_id,
1121                symbol: Ustr::from(symbol),
1122                width,
1123            })
1124            .await
1125        {
1126            // Rollback pending state on send failure
1127            self.subscriptions.mark_unsubscribe(&topic);
1128            return Err(e);
1129        }
1130
1131        Ok(())
1132    }
1133
1134    /// Unsubscribes from candle data for a symbol.
1135    ///
1136    /// # Errors
1137    ///
1138    /// Returns an error if the unsubscribe command cannot be sent.
1139    pub async fn unsubscribe_candles(&self, symbol: &str, width: AxCandleWidth) -> AxWsResult<()> {
1140        let _guard = self.subscribe_lock.lock().await;
1141        let request_id = self.next_request_id();
1142        let topic = format!("candles:{symbol}:{width:?}");
1143        let was_pending = self
1144            .subscriptions
1145            .pending_subscribe_topics()
1146            .contains(&topic);
1147
1148        if !self.is_subscribed_topic(&topic) {
1149            log::debug!("Not subscribed to {topic}, skipping unsubscribe");
1150            return Ok(());
1151        }
1152
1153        self.subscriptions.mark_unsubscribe(&topic);
1154
1155        if let Err(e) = self
1156            .send_cmd(HandlerCommand::UnsubscribeCandles {
1157                request_id,
1158                symbol: Ustr::from(symbol),
1159                width,
1160                topic: topic.clone(),
1161            })
1162            .await
1163        {
1164            self.restore_unsubscribe_state(&topic, was_pending);
1165            return Err(e);
1166        }
1167
1168        Ok(())
1169    }
1170
1171    fn restore_unsubscribe_state(&self, topic: &str, was_pending: bool) {
1172        self.subscriptions.confirm_unsubscribe(topic);
1173        self.subscriptions.mark_subscribe(topic);
1174        if !was_pending {
1175            self.subscriptions.confirm_subscribe(topic);
1176        }
1177    }
1178
1179    /// Returns a stream of WebSocket messages.
1180    ///
1181    /// # Panics
1182    ///
1183    /// Panics if called before `connect()` or if the stream has already been taken.
1184    pub fn stream(&mut self) -> impl futures_util::Stream<Item = AxDataWsMessage> + 'static {
1185        let rx = self
1186            .out_rx
1187            .take()
1188            .expect("Stream receiver already taken or client not connected - stream() can only be called once");
1189        let mut rx = Arc::try_unwrap(rx).expect(
1190            "Cannot take ownership of stream - client was cloned and other references exist",
1191        );
1192        async_stream::stream! {
1193            while let Some(msg) = rx.recv().await {
1194                yield msg;
1195            }
1196        }
1197    }
1198
1199    pub(crate) fn begin_shutdown(&self) {
1200        self.cancellation_token.load().cancel();
1201        self.signal.store(true, Ordering::Release);
1202    }
1203
1204    /// Disconnects the WebSocket connection gracefully.
1205    pub async fn disconnect(&self) {
1206        log::debug!("Disconnecting WebSocket");
1207        let _ = self.send_cmd(HandlerCommand::Disconnect).await;
1208    }
1209
1210    /// Closes the WebSocket connection and cleans up resources.
1211    ///
1212    /// # Errors
1213    ///
1214    /// Returns an error if the handler task fails or does not stop after abort.
1215    pub async fn close(&mut self) -> anyhow::Result<()> {
1216        let connect_lock = Arc::clone(&self.connect_lock);
1217        let _guard = connect_lock.lock().await;
1218        log::debug!("Closing WebSocket client");
1219
1220        // Send disconnect first to allow graceful cleanup before signal
1221        self.cancellation_token.load().cancel();
1222        let _ = self.send_cmd(HandlerCommand::Disconnect).await;
1223        tokio::time::sleep(Duration::from_millis(50)).await;
1224        self.signal.store(true, Ordering::Release);
1225
1226        let outcome = self
1227            .task_handle
1228            .finish(Duration::from_secs(2), Duration::from_secs(2))
1229            .await;
1230
1231        *self.reconnect_headers.lock() = None;
1232
1233        if let Some(control) = &self.socket_control {
1234            control.deregister();
1235        }
1236
1237        match outcome {
1238            None | Some(TaskJoinOutcome::Completed(()) | TaskJoinOutcome::Aborted) => Ok(()),
1239            Some(TaskJoinOutcome::Failed(error)) => Err(anyhow::anyhow!(
1240                "Architect AX data WebSocket handler failed: {error}"
1241            )),
1242            Some(TaskJoinOutcome::Incomplete) => Err(anyhow::anyhow!(
1243                "Architect AX data WebSocket handler did not stop after abort"
1244            )),
1245        }
1246    }
1247
1248    async fn send_cmd(&self, cmd: HandlerCommand) -> AxWsResult<()> {
1249        let guard = self.cmd_tx.read().await;
1250        guard
1251            .send(cmd)
1252            .map_err(|e| AxWsClientError::ChannelError(e.to_string()))
1253    }
1254}
1255
1256impl Drop for AxMdWebSocketClient {
1257    fn drop(&mut self) {
1258        if Arc::strong_count(&self.task_handle) == 1 && !self.task_handle.is_empty() {
1259            self.cancellation_token.load().cancel();
1260            self.signal.store(true, Ordering::Release);
1261            self.task_handle.abort();
1262
1263            if let Some(control) = &self.socket_control {
1264                control.deregister();
1265            }
1266        }
1267    }
1268}
1269
1270#[cfg(test)]
1271mod tests {
1272    use futures_util::StreamExt;
1273    use nautilus_live::task::TaskGroup;
1274    use nautilus_model::identifiers::InstrumentId;
1275    use nautilus_testkit::connection::race_command_with_publication;
1276    use rstest::rstest;
1277
1278    use super::*;
1279    use crate::{
1280        book::{recovery::spawn_subscription_task, sync::BookSyncTracker},
1281        websocket::data::subscription::SubscriptionOrder,
1282    };
1283
1284    #[tokio::test]
1285    async fn command_during_sender_publication_reaches_initialized_handler() {
1286        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
1287        let addr = listener.local_addr().unwrap();
1288        let (received_tx, mut received_rx) = tokio::sync::mpsc::unbounded_channel();
1289
1290        let server = tokio::spawn(async move {
1291            let (socket, _) = listener.accept().await.unwrap();
1292            let mut socket = tokio_tungstenite::accept_async(socket).await.unwrap();
1293            while let Some(Ok(message)) = socket.next().await {
1294                if let tokio_tungstenite::tungstenite::Message::Text(text) = message {
1295                    let payload: serde_json::Value = serde_json::from_str(text.as_str()).unwrap();
1296                    let _ = received_tx.send(payload);
1297                }
1298            }
1299        });
1300
1301        let url = format!("ws://{addr}");
1302        let mut ws_client =
1303            AxMdWebSocketClient::new(url, "startup-token", 30, TransportBackend::default(), None);
1304        let observer = ws_client.clone();
1305
1306        let command = HandlerCommand::Subscribe {
1307            request_id: 71,
1308            symbol: Ustr::from("BTCUSD"),
1309            spec: AxMdSubscriptionSpec::new(AxMarketDataLevel::Trades, None, None),
1310        };
1311
1312        race_command_with_publication(
1313            Arc::clone(&ws_client.cmd_tx),
1314            ws_client.connect(),
1315            move || command,
1316            || observer.is_active(),
1317        )
1318        .await
1319        .expect("connect failed");
1320        let received = tokio::time::timeout(Duration::from_secs(2), received_rx.recv()).await;
1321        ws_client.close().await.expect("disconnect failed");
1322        server.abort();
1323
1324        let payload = received
1325            .expect("startup command must reach server")
1326            .unwrap();
1327        assert_eq!(
1328            payload,
1329            serde_json::json!({
1330                "rid": 71,
1331                "type": "subscribe",
1332                "symbol": "BTCUSD",
1333                "level": "TRADES"
1334            })
1335        );
1336    }
1337
1338    #[rstest]
1339    fn test_auth_token_uses_secret_string_owner() {
1340        let client = AxMdWebSocketClient::new(
1341            "ws://localhost:9999/md/ws".to_string(),
1342            "initial-token".to_string(),
1343            30,
1344            TransportBackend::default(),
1345            None,
1346        );
1347
1348        client.set_auth_token("replacement-token".to_string());
1349
1350        let token = client.auth_token.lock();
1351        assert_eq!(
1352            token.as_ref().map(SecretString::expose_secret),
1353            Some("replacement-token")
1354        );
1355    }
1356
1357    #[tokio::test]
1358    async fn test_drop_aborts_handler_task() {
1359        let client = AxMdWebSocketClient::new(
1360            "ws://localhost:9999/md/ws".to_string(),
1361            "test_token".to_string(),
1362            30,
1363            TransportBackend::default(),
1364            None,
1365        );
1366        let (started_tx, started_rx) = tokio::sync::oneshot::channel();
1367        let (dropped_tx, dropped_rx) = tokio::sync::oneshot::channel::<()>();
1368        let handle = tokio::spawn(async move {
1369            let _dropped_tx = dropped_tx;
1370            started_tx.send(()).expect("started receiver");
1371            std::future::pending::<()>().await;
1372        });
1373
1374        client.task_handle.insert(handle);
1375        started_rx.await.expect("handler task started");
1376
1377        drop(client);
1378
1379        tokio::time::timeout(Duration::from_secs(5), dropped_rx)
1380            .await
1381            .expect("handler task future should be dropped")
1382            .expect_err("aborted task should drop its sender");
1383    }
1384
1385    #[rstest]
1386    fn test_effective_subscription_empty_returns_none() {
1387        let sdt = SymbolDataTypes::default();
1388        assert_eq!(sdt.effective_subscription(), None);
1389        assert!(sdt.is_empty());
1390    }
1391
1392    #[rstest]
1393    fn test_effective_subscription_book_level_takes_precedence() {
1394        let sdt = SymbolDataTypes {
1395            book_level: Some(AxMarketDataLevel::Level2),
1396            quotes: true,
1397            ..Default::default()
1398        };
1399        assert_eq!(
1400            sdt.effective_subscription(),
1401            Some(AxMdSubscriptionSpec::new(
1402                AxMarketDataLevel::Level2,
1403                Some(false),
1404                Some(false),
1405            ))
1406        );
1407        assert!(!sdt.is_empty());
1408    }
1409
1410    #[rstest]
1411    #[case(
1412        true,
1413        false,
1414        false,
1415        false,
1416        AxMarketDataLevel::Level1,
1417        Some(false),
1418        Some(false)
1419    )]
1420    #[case(false, true, false, false, AxMarketDataLevel::Trades, None, None)]
1421    #[case(
1422        false,
1423        false,
1424        true,
1425        false,
1426        AxMarketDataLevel::Level1,
1427        Some(false),
1428        Some(true)
1429    )]
1430    #[case(
1431        false,
1432        false,
1433        false,
1434        true,
1435        AxMarketDataLevel::Level1,
1436        Some(false),
1437        Some(true)
1438    )]
1439    fn test_effective_subscription_for_single_data_type(
1440        #[case] quotes: bool,
1441        #[case] trades: bool,
1442        #[case] mark_prices: bool,
1443        #[case] instrument_status: bool,
1444        #[case] level: AxMarketDataLevel,
1445        #[case] include_trades: Option<bool>,
1446        #[case] include_ticker: Option<bool>,
1447    ) {
1448        let sdt = SymbolDataTypes {
1449            quotes,
1450            trades,
1451            mark_prices,
1452            instrument_status,
1453            book_level: None,
1454        };
1455        assert_eq!(
1456            sdt.effective_subscription(),
1457            Some(AxMdSubscriptionSpec::new(
1458                level,
1459                include_trades,
1460                include_ticker,
1461            ))
1462        );
1463        assert!(!sdt.is_empty());
1464    }
1465
1466    #[rstest]
1467    #[case(false)]
1468    #[case(true)]
1469    #[tokio::test]
1470    async fn test_unsubscribe_send_failure_restores_subscription(#[case] was_pending: bool) {
1471        let client = AxMdWebSocketClient::new(
1472            "ws://localhost:9999/md/ws".to_string(),
1473            "test_token".to_string(),
1474            30,
1475            TransportBackend::default(),
1476            None,
1477        );
1478        let symbol = "EURUSD-PERP";
1479        let spec = AxMdSubscriptionSpec::new(AxMarketDataLevel::Level2, Some(false), Some(false));
1480        let topic = spec.topic(symbol);
1481        client.subscriptions.mark_subscribe(&topic);
1482        if !was_pending {
1483            client.subscriptions.confirm_subscribe(&topic);
1484        }
1485
1486        let error = client.send_unsubscribe(symbol, spec).await.unwrap_err();
1487
1488        assert_eq!(error.to_string(), "Channel error: channel closed");
1489        assert_eq!(client.subscription_count(), usize::from(!was_pending));
1490        assert_eq!(client.subscriptions.all_topics(), vec![topic]);
1491        assert_eq!(
1492            client.subscriptions.pending_subscribe_topics().len(),
1493            usize::from(was_pending)
1494        );
1495        assert!(client.subscriptions.pending_unsubscribe_topics().is_empty());
1496    }
1497
1498    #[rstest]
1499    #[case(false)]
1500    #[case(true)]
1501    #[tokio::test]
1502    async fn test_unsubscribe_candles_send_failure_restores_subscription(
1503        #[case] was_pending: bool,
1504    ) {
1505        let client = AxMdWebSocketClient::new(
1506            "ws://localhost:9999/md/ws".to_string(),
1507            "test_token".to_string(),
1508            30,
1509            TransportBackend::default(),
1510            None,
1511        );
1512        let symbol = "EURUSD-PERP";
1513        let width = AxCandleWidth::Minutes1;
1514        let topic = format!("candles:{symbol}:{width:?}");
1515        client.subscriptions.mark_subscribe(&topic);
1516        if !was_pending {
1517            client.subscriptions.confirm_subscribe(&topic);
1518        }
1519
1520        let error = client.unsubscribe_candles(symbol, width).await.unwrap_err();
1521
1522        assert_eq!(error.to_string(), "Channel error: channel closed");
1523        assert_eq!(client.subscription_count(), usize::from(!was_pending));
1524        assert_eq!(client.subscriptions.all_topics(), vec![topic]);
1525        assert_eq!(
1526            client.subscriptions.pending_subscribe_topics().len(),
1527            usize::from(was_pending)
1528        );
1529        assert!(client.subscriptions.pending_unsubscribe_topics().is_empty());
1530    }
1531
1532    #[rstest]
1533    #[tokio::test]
1534    async fn test_unsubscribe_candles_skips_untracked_topic() {
1535        let client = AxMdWebSocketClient::new(
1536            "ws://localhost:9999/md/ws".to_string(),
1537            "test_token".to_string(),
1538            30,
1539            TransportBackend::default(),
1540            None,
1541        );
1542
1543        client
1544            .unsubscribe_candles("EURUSD-PERP", AxCandleWidth::Minutes1)
1545            .await
1546            .unwrap();
1547
1548        assert_eq!(client.subscription_count(), 0);
1549        assert!(client.subscriptions.all_topics().is_empty());
1550        assert!(client.subscriptions.pending_subscribe_topics().is_empty());
1551        assert!(client.subscriptions.pending_unsubscribe_topics().is_empty());
1552    }
1553
1554    const SYMBOL: &str = "EURUSD-PERP";
1555
1556    // Returns a client whose handler commands the test receives, with `current` already streaming
1557    async fn book_client(
1558        current: SymbolDataTypes,
1559    ) -> (
1560        AxMdWebSocketClient,
1561        tokio::sync::mpsc::UnboundedReceiver<HandlerCommand>,
1562    ) {
1563        let client = AxMdWebSocketClient::new(
1564            "ws://localhost:9999/md/ws".to_string(),
1565            "test_token".to_string(),
1566            30,
1567            TransportBackend::default(),
1568            None,
1569        );
1570        let (cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
1571        *client.cmd_tx.write().await = cmd_tx;
1572
1573        if let Some(spec) = current.effective_subscription() {
1574            let topic = spec.topic(SYMBOL);
1575            client.subscriptions.mark_subscribe(&topic);
1576            client.subscriptions.confirm_subscribe(&topic);
1577            client.symbol_data_types.insert(SYMBOL.to_string(), current);
1578        }
1579
1580        (client, cmd_rx)
1581    }
1582
1583    #[rstest]
1584    #[case::no_stream(SymbolDataTypes::default(), None, false)]
1585    #[case::quote_stream(
1586        SymbolDataTypes { quotes: true, ..Default::default() },
1587        Some("EURUSD-PERP:Level1:false:false"),
1588        false
1589    )]
1590    #[case::book_stream(
1591        SymbolDataTypes { book_level: Some(AxMarketDataLevel::Level2), ..Default::default() },
1592        None,
1593        true
1594    )]
1595    #[tokio::test]
1596    async fn test_subscribe_book_deltas_gated_writes_book_stream(
1597        #[case] current: SymbolDataTypes,
1598        #[case] unsubscribed: Option<&str>,
1599        #[case] replaced: bool,
1600    ) {
1601        let quotes = current.quotes;
1602        let (client, mut cmd_rx) = book_client(current).await;
1603        let gate = SnapshotGate::default();
1604        gate.lock().close();
1605
1606        let subscribe = client.subscribe_book_deltas_gated(
1607            Ustr::from(SYMBOL),
1608            AxMarketDataLevel::Level2,
1609            CancellationToken::new(),
1610            gate,
1611        );
1612
1613        let handler = async {
1614            let mut topics = Vec::new();
1615
1616            loop {
1617                match cmd_rx.recv().await.expect("command queued") {
1618                    HandlerCommand::Unsubscribe { topic, .. } => topics.push(topic),
1619                    HandlerCommand::WriteBook {
1620                        spec,
1621                        unsubscribe_request_id,
1622                        completion,
1623                        ..
1624                    } => {
1625                        completion.send(Ok(())).unwrap();
1626                        return (topics, spec, unsubscribe_request_id.is_some());
1627                    }
1628                    other => panic!("unexpected command {other:?}"),
1629                }
1630            }
1631        };
1632
1633        let (result, (topics, spec, replaces)) = tokio::join!(subscribe, handler);
1634        let types = client
1635            .symbol_data_types
1636            .load()
1637            .get(SYMBOL)
1638            .cloned()
1639            .unwrap();
1640
1641        assert!(result.is_ok());
1642        assert_eq!(
1643            topics,
1644            unsubscribed
1645                .map(ToString::to_string)
1646                .into_iter()
1647                .collect::<Vec<_>>()
1648        );
1649        assert_eq!(
1650            spec,
1651            AxMdSubscriptionSpec::new(AxMarketDataLevel::Level2, Some(false), Some(false))
1652        );
1653        assert_eq!(replaces, replaced);
1654        assert_eq!(types.book_level, Some(AxMarketDataLevel::Level2));
1655        assert_eq!(types.quotes, quotes);
1656        assert_eq!(client.subscriptions.all_topics(), vec![spec.topic(SYMBOL)]);
1657    }
1658
1659    #[rstest]
1660    #[tokio::test]
1661    async fn test_book_subscription_write_failure_starts_recovery() {
1662        let (client, mut cmd_rx) = book_client(SymbolDataTypes::default()).await;
1663        let book_sync = BookSyncTracker::default();
1664        let tasks = TaskGroup::new();
1665        let instrument_id = InstrumentId::from("EURUSD-PERP.AX");
1666
1667        spawn_subscription_task(
1668            instrument_id,
1669            AxMarketDataLevel::Level2,
1670            SubscriptionOrder::default().next(),
1671            book_sync.clone(),
1672            client.clone(),
1673            Duration::from_secs(10),
1674            &tasks.spawner().unwrap(),
1675        );
1676
1677        let mut replaces = Vec::new();
1678
1679        for _ in 0..2 {
1680            let command = tokio::time::timeout(Duration::from_secs(5), cmd_rx.recv())
1681                .await
1682                .expect("book write queued")
1683                .expect("command channel open");
1684
1685            let HandlerCommand::WriteBook {
1686                unsubscribe_request_id,
1687                completion,
1688                ..
1689            } = command
1690            else {
1691                panic!("expected a book write, was {command:?}");
1692            };
1693
1694            replaces.push(unsubscribe_request_id.is_some());
1695
1696            // The initial write fails in transport, which recovery retries
1697            let _ = completion.send(Err(AxWsClientError::Transport("write failed".to_string())));
1698        }
1699
1700        let owned = book_sync.claim_recovery(instrument_id).is_none();
1701        tasks.begin_shutdown();
1702
1703        assert_eq!(replaces, [false, true]);
1704        assert!(owned, "the running recovery owns the book");
1705    }
1706
1707    #[rstest]
1708    #[tokio::test]
1709    async fn test_resubscribe_book_gated_echoes_current_subscription() {
1710        let current = SymbolDataTypes {
1711            mark_prices: true,
1712            book_level: Some(AxMarketDataLevel::Level2),
1713            ..Default::default()
1714        };
1715
1716        let (client, mut cmd_rx) = book_client(current).await;
1717
1718        let resubscribe = client.resubscribe_book_gated(
1719            Ustr::from(SYMBOL),
1720            CancellationToken::new(),
1721            SnapshotGate::default(),
1722        );
1723
1724        let handler = async {
1725            match cmd_rx.recv().await.expect("command queued") {
1726                HandlerCommand::WriteBook {
1727                    request_id,
1728                    unsubscribe_request_id,
1729                    symbol,
1730                    spec,
1731                    completion,
1732                    ..
1733                } => {
1734                    completion.send(Ok(())).unwrap();
1735                    (request_id, unsubscribe_request_id, symbol, spec)
1736                }
1737                other => panic!("unexpected command {other:?}"),
1738            }
1739        };
1740
1741        let (result, (request_id, unsubscribe_request_id, symbol, spec)) =
1742            tokio::join!(resubscribe, handler);
1743
1744        assert!(result.is_ok());
1745        assert_eq!(request_id, 1);
1746        assert_eq!(unsubscribe_request_id, Some(2));
1747        assert_eq!(symbol, Ustr::from(SYMBOL));
1748        assert_eq!(
1749            spec,
1750            AxMdSubscriptionSpec::new(AxMarketDataLevel::Level2, Some(false), Some(true))
1751        );
1752        assert!(cmd_rx.try_recv().is_err());
1753    }
1754
1755    #[rstest]
1756    #[case::not_subscribed(
1757        SymbolDataTypes { quotes: true, ..Default::default() },
1758        false,
1759        "Client error: Book deltas for EURUSD-PERP are no longer subscribed"
1760    )]
1761    #[case::cancelled(
1762        SymbolDataTypes { book_level: Some(AxMarketDataLevel::Level2), ..Default::default() },
1763        true,
1764        "Client error: Book recovery canceled"
1765    )]
1766    #[tokio::test]
1767    async fn test_resubscribe_book_gated_refuses_without_write(
1768        #[case] current: SymbolDataTypes,
1769        #[case] cancelled: bool,
1770        #[case] expected: &str,
1771    ) {
1772        let (client, mut cmd_rx) = book_client(current).await;
1773        let cancel = CancellationToken::new();
1774
1775        if cancelled {
1776            cancel.cancel();
1777        }
1778
1779        let error = client
1780            .resubscribe_book_gated(Ustr::from(SYMBOL), cancel, SnapshotGate::default())
1781            .await
1782            .unwrap_err();
1783
1784        assert_eq!(error.to_string(), expected);
1785        assert!(cmd_rx.try_recv().is_err());
1786    }
1787}