Skip to main content

nautilus_architect_ax/websocket/orders/
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//! Orders WebSocket client for Ax.
17
18use std::{
19    fmt::Debug,
20    num::NonZeroU32,
21    sync::{
22        Arc,
23        atomic::{AtomicBool, AtomicI64, AtomicU8, Ordering},
24    },
25    time::Duration,
26};
27
28use arc_swap::ArcSwap;
29use dashmap::{DashMap, mapref::entry::Entry};
30use nautilus_common::cache::InstrumentLookupError;
31use nautilus_core::{
32    AtomicMap, UUID4,
33    nanos::UnixNanos,
34    string::secret::SecretString,
35    time::{AtomicTime, get_atomic_clock_realtime},
36};
37use nautilus_live::{
38    SocketControl,
39    task::{SharedTaskSlot, TaskJoinOutcome},
40};
41use nautilus_model::{
42    enums::TimeInForce,
43    events::OrderInitialized,
44    identifiers::{AccountId, ClientOrderId, InstrumentId, StrategyId, TraderId, VenueOrderId},
45    instruments::{Instrument, InstrumentAny},
46    types::{Price, Quantity},
47};
48use nautilus_network::{
49    ConnectionUrl,
50    http::create_standard_nautilus_headers,
51    mode::ConnectionMode,
52    websocket::{
53        AuthTracker, InitialConnectRetryPolicy, PingHandler, ReconnectHeaders, TransportBackend,
54        WebSocketClient, WebSocketConfig, auth::AuthResultReceiver, channel_epoch_message_handler,
55    },
56};
57use parking_lot::Mutex;
58use tokio_util::sync::CancellationToken;
59use ustr::Ustr;
60
61use super::handler::{AxOrdersWsFeedHandler, HandlerCommand, WsOrderInfo};
62use crate::{
63    common::{
64        consts::AX_NAUTILUS_TAG,
65        enums::{AxOrderRequestType, AxOrderSide, AxSelfTradeBehavior, AxTimeInForce},
66        parse::{client_order_id_to_cid, quantity_to_contracts},
67    },
68    websocket::messages::{AxOrdersWsMessage, AxWsPlaceOrder, OrderMetadata},
69};
70
71/// Result type for Ax orders WebSocket operations.
72pub type AxOrdersWsResult<T> = Result<T, AxOrdersWsClientError>;
73
74/// Shared caches for order state tracking between the client and consumers.
75#[derive(Debug, Clone)]
76pub struct OrdersCaches {
77    /// Maps client order IDs to order metadata.
78    pub orders_metadata: Arc<DashMap<ClientOrderId, OrderMetadata>>,
79    /// Maps venue order IDs to client order IDs.
80    pub venue_to_client_id: Arc<DashMap<VenueOrderId, ClientOrderId>>,
81    /// Maps AX cid values to client order IDs.
82    pub cid_to_client_order_id: Arc<DashMap<u64, ClientOrderId>>,
83    pub(crate) pending_modifies: Arc<DashMap<VenueOrderId, (ClientOrderId, usize, bool)>>,
84}
85
86impl Default for OrdersCaches {
87    fn default() -> Self {
88        Self {
89            orders_metadata: Arc::new(DashMap::new()),
90            venue_to_client_id: Arc::new(DashMap::new()),
91            cid_to_client_order_id: Arc::new(DashMap::new()),
92            pending_modifies: Arc::new(DashMap::new()),
93        }
94    }
95}
96
97/// Error type for the Ax orders WebSocket client.
98#[derive(Debug, Clone)]
99pub enum AxOrdersWsClientError {
100    /// Transport/connection error.
101    Transport(String),
102    /// Channel send error.
103    ChannelError(String),
104    /// Authentication error.
105    AuthenticationError(String),
106    /// Client-side validation error.
107    ClientError(String),
108}
109
110impl core::fmt::Display for AxOrdersWsClientError {
111    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
112        match self {
113            Self::Transport(msg) => write!(f, "Transport error: {msg}"),
114            Self::ChannelError(msg) => write!(f, "Channel error: {msg}"),
115            Self::AuthenticationError(msg) => write!(f, "Authentication error: {msg}"),
116            Self::ClientError(msg) => write!(f, "Client error: {msg}"),
117        }
118    }
119}
120
121impl std::error::Error for AxOrdersWsClientError {}
122
123impl From<&'static str> for AxOrdersWsClientError {
124    fn from(msg: &'static str) -> Self {
125        Self::ClientError(msg.to_string())
126    }
127}
128
129/// Orders WebSocket client for Ax.
130///
131/// Provides authenticated order management including placing, canceling,
132/// and monitoring order status via WebSocket.
133pub struct AxOrdersWebSocketClient {
134    clock: &'static AtomicTime,
135    url: ConnectionUrl,
136    heartbeat: Option<u64>,
137    reconnect_headers: Arc<Mutex<Option<ReconnectHeaders>>>,
138    connection_mode: Arc<ArcSwap<AtomicU8>>,
139    cmd_tx: Arc<tokio::sync::RwLock<tokio::sync::mpsc::UnboundedSender<HandlerCommand>>>,
140    out_rx: Option<Arc<tokio::sync::mpsc::UnboundedReceiver<AxOrdersWsMessage>>>,
141    signal: Arc<AtomicBool>,
142    cancellation_token: Arc<ArcSwap<CancellationToken>>,
143    task_handle: Arc<SharedTaskSlot<()>>,
144    connect_lock: Arc<tokio::sync::Mutex<()>>,
145    auth_tracker: AuthTracker,
146    instruments_cache: Arc<AtomicMap<Ustr, InstrumentAny>>,
147    caches: OrdersCaches,
148    request_id_counter: Arc<AtomicI64>,
149    account_id: AccountId,
150    trader_id: TraderId,
151    transport_backend: TransportBackend,
152    proxy_url: Option<SecretString>,
153    cancel_on_disconnect: Option<bool>,
154    socket_control: Option<SocketControl>,
155}
156
157impl Debug for AxOrdersWebSocketClient {
158    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
159        f.debug_struct(stringify!(AxOrdersWebSocketClient))
160            .field("url", &self.url)
161            .field("heartbeat", &self.heartbeat)
162            .field("account_id", &self.account_id)
163            .finish()
164    }
165}
166
167impl Clone for AxOrdersWebSocketClient {
168    fn clone(&self) -> Self {
169        Self {
170            clock: self.clock,
171            url: self.url.clone(),
172            heartbeat: self.heartbeat,
173            reconnect_headers: Arc::clone(&self.reconnect_headers),
174            connection_mode: Arc::clone(&self.connection_mode),
175            cmd_tx: Arc::clone(&self.cmd_tx),
176            out_rx: None, // Each clone gets its own receiver
177            signal: Arc::clone(&self.signal),
178            cancellation_token: Arc::clone(&self.cancellation_token),
179            task_handle: Arc::clone(&self.task_handle),
180            connect_lock: Arc::clone(&self.connect_lock),
181            auth_tracker: self.auth_tracker.clone(),
182            instruments_cache: Arc::clone(&self.instruments_cache),
183            caches: self.caches.clone(),
184            request_id_counter: Arc::clone(&self.request_id_counter),
185            account_id: self.account_id,
186            trader_id: self.trader_id,
187            transport_backend: self.transport_backend,
188            proxy_url: self.proxy_url.clone(),
189            cancel_on_disconnect: self.cancel_on_disconnect,
190            socket_control: self.socket_control.clone(),
191        }
192    }
193}
194
195impl AxOrdersWebSocketClient {
196    fn initial_connect_retry_policy() -> InitialConnectRetryPolicy {
197        InitialConnectRetryPolicy {
198            max_attempts: NonZeroU32::new(5).expect("initial connect attempts must be non-zero"),
199            delay_initial: Duration::from_millis(500),
200            delay_max: Duration::from_secs(5),
201            backoff_factor: 2.0,
202            jitter_ms: 250,
203        }
204    }
205
206    /// Creates a new Ax orders WebSocket client.
207    #[must_use]
208    pub fn new(
209        url: String,
210        account_id: AccountId,
211        trader_id: TraderId,
212        heartbeat: u64,
213        transport_backend: TransportBackend,
214        proxy_url: Option<String>,
215    ) -> Self {
216        let (cmd_tx, _cmd_rx) = tokio::sync::mpsc::unbounded_channel::<HandlerCommand>();
217
218        let initial_mode = AtomicU8::new(ConnectionMode::Closed.as_u8());
219        let connection_mode = Arc::new(ArcSwap::from_pointee(initial_mode));
220
221        Self {
222            clock: get_atomic_clock_realtime(),
223            url: url.into(),
224            heartbeat: Some(heartbeat),
225            reconnect_headers: Arc::new(Mutex::new(None)),
226            connection_mode,
227            cmd_tx: Arc::new(tokio::sync::RwLock::new(cmd_tx)),
228            out_rx: None,
229            signal: Arc::new(AtomicBool::new(false)),
230            cancellation_token: Arc::new(ArcSwap::from_pointee(CancellationToken::new())),
231            task_handle: Arc::new(SharedTaskSlot::new()),
232            connect_lock: Arc::new(tokio::sync::Mutex::new(())),
233            auth_tracker: AuthTracker::default(),
234            instruments_cache: Arc::new(AtomicMap::new()),
235            caches: OrdersCaches::default(),
236            request_id_counter: Arc::new(AtomicI64::new(1)),
237            account_id,
238            trader_id,
239            transport_backend,
240            proxy_url: proxy_url.map(SecretString::from),
241            cancel_on_disconnect: None,
242            socket_control: None,
243        }
244    }
245
246    pub(crate) fn with_cancel_on_disconnect(mut self, enabled: bool) -> AxOrdersWsResult<Self> {
247        let url = orders_ws_url(self.url.expose(), enabled)?;
248        self.url = url.into();
249        self.cancel_on_disconnect = Some(enabled);
250        Ok(self)
251    }
252
253    /// Configures socket state reporting and reconnect control.
254    #[must_use]
255    pub fn with_socket_control(mut self, control: SocketControl) -> Self {
256        self.socket_control = Some(control);
257        self
258    }
259
260    fn generate_ts_init(&self) -> UnixNanos {
261        self.clock.get_time_ns()
262    }
263
264    /// Returns the WebSocket URL.
265    #[must_use]
266    pub fn url(&self) -> &str {
267        self.url.expose()
268    }
269
270    /// Returns the account ID.
271    #[must_use]
272    pub fn account_id(&self) -> AccountId {
273        self.account_id
274    }
275
276    /// Returns whether the client is currently connected and active.
277    #[must_use]
278    pub fn is_active(&self) -> bool {
279        let connection_mode_arc = self.connection_mode.load();
280        ConnectionMode::from_atomic(&connection_mode_arc).is_active()
281            && !self.signal.load(Ordering::Acquire)
282    }
283
284    pub(crate) fn is_authenticated(&self) -> bool {
285        self.auth_tracker.is_authenticated()
286    }
287
288    /// Returns whether the client is closed.
289    #[must_use]
290    pub fn is_closed(&self) -> bool {
291        let connection_mode_arc = self.connection_mode.load();
292        ConnectionMode::from_atomic(&connection_mode_arc).is_closed()
293            || self.signal.load(Ordering::Acquire)
294    }
295
296    /// Generates a unique request ID.
297    fn next_request_id(&self) -> i64 {
298        self.request_id_counter.fetch_add(1, Ordering::Relaxed)
299    }
300
301    /// Caches an instrument for use during message parsing.
302    pub fn cache_instrument(&self, instrument: InstrumentAny) {
303        let symbol = instrument.symbol().inner();
304        self.instruments_cache.insert(symbol, instrument);
305    }
306
307    /// Caches multiple instruments for use during message parsing.
308    pub fn cache_instruments(&self, instruments: &[InstrumentAny]) {
309        self.instruments_cache.rcu(|m| {
310            for inst in instruments {
311                m.insert(inst.symbol().inner(), inst.clone());
312            }
313        });
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: &str) -> AxOrdersWsResult<()> {
324        let value = format!("Bearer {token}");
325
326        if let Some(headers) = self.reconnect_headers.lock().as_ref() {
327            headers
328                .update("Authorization", &value)
329                .map_err(|e| AxOrdersWsClientError::Transport(e.to_string()))?;
330        }
331        Ok(())
332    }
333
334    /// Returns a cached instrument by symbol.
335    #[must_use]
336    pub fn get_cached_instrument(&self, symbol: &Ustr) -> Option<InstrumentAny> {
337        self.instruments_cache.get_cloned(symbol)
338    }
339
340    /// Returns the shared order caches.
341    #[must_use]
342    pub fn caches(&self) -> &OrdersCaches {
343        &self.caches
344    }
345
346    /// Returns the instruments cache.
347    #[must_use]
348    pub fn instruments_cache(&self) -> Arc<AtomicMap<Ustr, InstrumentAny>> {
349        Arc::clone(&self.instruments_cache)
350    }
351
352    /// Returns the orders metadata cache.
353    #[must_use]
354    pub fn orders_metadata(&self) -> &Arc<DashMap<ClientOrderId, OrderMetadata>> {
355        &self.caches.orders_metadata
356    }
357
358    /// Returns the cid to client order ID mapping for order correlation.
359    #[must_use]
360    pub fn cid_to_client_order_id(&self) -> &Arc<DashMap<u64, ClientOrderId>> {
361        &self.caches.cid_to_client_order_id
362    }
363
364    /// Resolves a cid to a ClientOrderId if the mapping exists.
365    #[must_use]
366    pub fn resolve_cid(&self, cid: u64) -> Option<ClientOrderId> {
367        self.caches.cid_to_client_order_id.get(&cid).map(|v| *v)
368    }
369
370    /// Registers an external order with the WebSocket handler for event tracking.
371    ///
372    /// This allows the handler to create proper events (e.g., OrderCanceled, OrderFilled)
373    /// for orders that were reconciled externally and not submitted through this client.
374    ///
375    /// Returns `false` if the instrument is not cached (registration skipped).
376    pub fn register_external_order(
377        &self,
378        client_order_id: ClientOrderId,
379        venue_order_id: VenueOrderId,
380        instrument_id: InstrumentId,
381        strategy_id: StrategyId,
382    ) -> bool {
383        if self.caches.orders_metadata.contains_key(&client_order_id) {
384            return true;
385        }
386
387        // Required for correct precision on fills
388        let symbol = instrument_id.symbol.inner();
389        let Some(instrument) = self.get_cached_instrument(&symbol) else {
390            log::warn!(
391                "Cannot register external order {client_order_id}: \
392                 instrument {instrument_id} not in cache"
393            );
394            return false;
395        };
396
397        let metadata = OrderMetadata {
398            trader_id: self.trader_id,
399            strategy_id,
400            instrument_id,
401            client_order_id,
402            order_init: None,
403            is_accepted: true,
404            venue_order_id: Some(venue_order_id),
405            ts_init: self.generate_ts_init(),
406            size_precision: instrument.size_precision(),
407            price_precision: instrument.price_precision(),
408            quote_currency: instrument.quote_currency(),
409        };
410
411        self.caches
412            .orders_metadata
413            .insert(client_order_id, metadata);
414        self.caches
415            .venue_to_client_id
416            .insert(venue_order_id, client_order_id);
417
418        log::debug!(
419            "Registered external order {client_order_id} ({venue_order_id}) for {instrument_id} [{strategy_id}]"
420        );
421
422        true
423    }
424
425    /// Establishes the WebSocket connection with authentication.
426    ///
427    /// # Arguments
428    ///
429    /// * `bearer_token` - The bearer token for authentication.
430    ///
431    /// # Errors
432    ///
433    /// Returns an error if the connection cannot be established.
434    pub async fn connect(&mut self, bearer_token: &str) -> AxOrdersWsResult<()> {
435        let connect_lock = Arc::clone(&self.connect_lock);
436        let _guard = connect_lock.lock().await;
437
438        self.finish_previous_handler().await?;
439
440        self.signal.store(false, Ordering::Release);
441        let cancellation_token = CancellationToken::new();
442        self.cancellation_token
443            .store(Arc::new(cancellation_token.clone()));
444
445        let (raw_handler, raw_rx) = channel_epoch_message_handler();
446
447        // No-op ping handler: handler owns the WebSocketClient and responds to pings directly
448        let ping_handler: PingHandler = Arc::new(move |_payload: Vec<u8>| {
449            // Handler responds to pings internally via select! loop
450        });
451
452        let mut headers = create_standard_nautilus_headers();
453        headers.push((
454            "Authorization".to_string(),
455            format!("Bearer {bearer_token}"),
456        ));
457
458        let config = WebSocketConfig {
459            url: self.url.expose().to_owned(),
460            headers,
461            heartbeat_interval_secs: self.heartbeat,
462            heartbeat_payload: None, // Ax server sends heartbeats
463            connect_timeout_ms: Some(5_000),
464            reconnect_delay_initial_ms: Some(500),
465            reconnect_delay_max_ms: Some(5_000),
466            reconnect_backoff_factor: Some(1.5),
467            reconnect_jitter_ms: Some(250),
468            reconnect_max_attempts: None,
469            heartbeat_timeout_secs: None,
470            idle_timeout_ms: None,
471            writer_capacity: None,
472            backend: self.transport_backend,
473            proxy_url: self
474                .proxy_url
475                .as_ref()
476                .map(|url| url.expose_secret().to_owned()),
477            max_message_size_bytes: None,
478            max_frame_size_bytes: None,
479        };
480
481        let client = WebSocketClient::epoch_builder()
482            .config(config.clone())
483            .epoch_handler(raw_handler.clone())
484            .ping_handler(ping_handler.clone())
485            .initial_connect_retry_policy(Self::initial_connect_retry_policy())
486            .cancellation_token(cancellation_token)
487            .maybe_state_sink(self.socket_control.as_ref().map(SocketControl::sink))
488            .connect()
489            .await
490            .map_err(|e| {
491                AxOrdersWsClientError::Transport(format!(
492                    "WebSocket connection failed: {}: {}",
493                    self.url.origin(),
494                    e.redacted_message()
495                ))
496            })?;
497
498        if self.cancel_on_disconnect.is_some() {
499            client.set_auth_tracker(self.auth_tracker.clone(), true);
500        }
501
502        let connection_mode = client.connection_mode_atomic();
503        let reconnect_handle = client.reconnect_handle();
504        *self.reconnect_headers.lock() = Some(client.reconnect_headers());
505
506        let (out_tx, out_rx) = tokio::sync::mpsc::unbounded_channel::<AxOrdersWsMessage>();
507        self.out_rx = Some(Arc::new(out_rx));
508
509        let (cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel::<HandlerCommand>();
510        cmd_tx
511            .send(HandlerCommand::SetClient(client))
512            .map_err(|e| AxOrdersWsClientError::ChannelError(e.to_string()))?;
513
514        if self.cancel_on_disconnect.is_none() {
515            cmd_tx
516                .send(HandlerCommand::SessionAuthenticated)
517                .map_err(|e| AxOrdersWsClientError::ChannelError(e.to_string()))?;
518        }
519
520        {
521            let mut command_sender = self.cmd_tx.write().await;
522            *command_sender = cmd_tx.clone();
523            self.connection_mode.store(connection_mode);
524        }
525
526        let login = self.cancel_on_disconnect.map(|_| self.auth_tracker.begin());
527        let cancel_on_disconnect = self.cancel_on_disconnect;
528        let signal = Arc::clone(&self.signal);
529        let auth_tracker = self.auth_tracker.clone();
530        let orders_metadata = Arc::clone(&self.caches.orders_metadata);
531        let venue_to_client_order_id = Arc::clone(&self.caches.venue_to_client_id);
532
533        if let Err(e) = self.task_handle.spawn(async move {
534            let mut handler = AxOrdersWsFeedHandler::new(
535                signal.clone(),
536                cmd_rx,
537                raw_rx,
538                auth_tracker.clone(),
539                cancel_on_disconnect,
540                orders_metadata,
541                venue_to_client_order_id,
542            );
543
544            while let Some(msg) = handler.next().await {
545                if matches!(msg, AxOrdersWsMessage::Reconnected) {
546                    log::info!("WebSocket reconnected, authentication will be restored");
547                }
548
549                if out_tx.send(msg).is_err() {
550                    log::debug!("Output channel closed");
551                    break;
552                }
553            }
554
555            log::debug!("Handler loop exited");
556        }) {
557            self.out_rx = None;
558
559            if login.is_some() {
560                self.auth_tracker
561                    .fail("Failed to start orders WebSocket handler");
562            }
563
564            return Err(AxOrdersWsClientError::Transport(format!(
565                "Failed to start WebSocket handler task: {e}"
566            )));
567        }
568
569        if let Some(receiver) = login {
570            self.await_login(receiver).await?;
571        }
572
573        if let Some(control) = &self.socket_control {
574            control.register(move || reconnect_handle.request_reconnect());
575        }
576
577        Ok(())
578    }
579
580    async fn finish_previous_handler(&self) -> AxOrdersWsResult<()> {
581        if !self.task_handle.is_empty() && !self.task_handle.is_finished() {
582            return Err(AxOrdersWsClientError::ClientError(
583                "WebSocket handler is already running".to_string(),
584            ));
585        }
586
587        if let Some(outcome) = self
588            .task_handle
589            .finish(Duration::from_secs(2), Duration::from_secs(2))
590            .await
591        {
592            match outcome {
593                TaskJoinOutcome::Completed(()) | TaskJoinOutcome::Aborted => {}
594                TaskJoinOutcome::Failed(error) => {
595                    return Err(AxOrdersWsClientError::ClientError(format!(
596                        "Previous WebSocket handler failed: {error}"
597                    )));
598                }
599                TaskJoinOutcome::Incomplete => {
600                    return Err(AxOrdersWsClientError::ClientError(
601                        "Previous WebSocket handler did not stop within shutdown bounds"
602                            .to_string(),
603                    ));
604                }
605            }
606        }
607
608        Ok(())
609    }
610
611    async fn await_login(&mut self, receiver: AuthResultReceiver) -> AxOrdersWsResult<()> {
612        let error = match receiver.await {
613            Ok(Ok(())) => None,
614            Ok(Err(message)) => Some(message),
615            Err(_) => Some("Orders WebSocket login channel closed".to_string()),
616        };
617
618        let Some(error) = error else {
619            return Ok(());
620        };
621
622        self.auth_tracker.fail(error.clone());
623
624        if let Err(cleanup_error) = self.close_inner().await {
625            return Err(AxOrdersWsClientError::AuthenticationError(format!(
626                "{error}; cleanup failed: {cleanup_error}"
627            )));
628        }
629
630        Err(AxOrdersWsClientError::AuthenticationError(error))
631    }
632
633    /// Submits the AX priced order shape using Nautilus domain types.
634    ///
635    /// Retains `order_init` for event correlation and the original order type and side.
636    /// The remaining arguments describe the current wire order, including a market order's
637    /// preview price and IOC time-in-force. `self_trade` carries the venue `st` option parsed
638    /// from strategy order params.
639    ///
640    /// # Errors
641    ///
642    /// Returns an error if:
643    /// - The time-in-force is not supported.
644    /// - The instrument is not found in the cache.
645    /// - The order command cannot be sent.
646    pub async fn submit_order(
647        &self,
648        order_init: &OrderInitialized,
649        quantity: Quantity,
650        time_in_force: TimeInForce,
651        price: Price,
652        post_only: bool,
653        self_trade: Option<AxSelfTradeBehavior>,
654    ) -> AxOrdersWsResult<i64> {
655        let trader_id = order_init.trader_id;
656        let strategy_id = order_init.strategy_id;
657        let instrument_id = order_init.instrument_id;
658        let client_order_id = order_init.client_order_id;
659        let order_side = order_init.order_side;
660        // Get instrument from cache for precision
661        let symbol = instrument_id.symbol.inner();
662        let instrument = self.get_cached_instrument(&symbol).ok_or_else(|| {
663            AxOrdersWsClientError::ClientError(
664                InstrumentLookupError::not_found(instrument_id).to_string(),
665            )
666        })?;
667
668        let ax_side = AxOrderSide::from(order_side);
669
670        let qty_contracts = quantity_to_contracts(quantity)
671            .map_err(|e| AxOrdersWsClientError::ClientError(e.to_string()))?;
672
673        let request_id = self.next_request_id();
674        let ax_tif = AxTimeInForce::try_from(time_in_force)?;
675        let cid = client_order_id_to_cid(&client_order_id);
676
677        reserve_cid_mapping(&self.caches, cid, client_order_id)?;
678
679        // Store order metadata for event correlation (after validation to avoid stale entries)
680        let metadata = OrderMetadata {
681            trader_id,
682            strategy_id,
683            instrument_id,
684            client_order_id,
685            order_init: Some(order_init.clone()),
686            is_accepted: false,
687            venue_order_id: None,
688            ts_init: self.generate_ts_init(),
689            size_precision: instrument.size_precision(),
690            price_precision: instrument.price_precision(),
691            quote_currency: instrument.quote_currency(),
692        };
693        self.caches
694            .orders_metadata
695            .insert(client_order_id, metadata);
696
697        let order = AxWsPlaceOrder {
698            rid: request_id,
699            t: AxOrderRequestType::PlaceOrder,
700            s: symbol,
701            d: ax_side,
702            q: qty_contracts,
703            p: price.as_decimal(),
704            tif: ax_tif,
705            po: post_only,
706            st: self_trade,
707            tag: Some(AX_NAUTILUS_TAG.to_string()),
708            cid: Some(cid),
709        };
710
711        let order_info = WsOrderInfo {
712            client_order_id,
713            symbol,
714            cid,
715        };
716
717        let result = self
718            .send_cmd(HandlerCommand::PlaceOrder {
719                request_id,
720                order,
721                order_info,
722            })
723            .await;
724
725        result?;
726        Ok(request_id)
727    }
728
729    /// Cancels an order via WebSocket.
730    ///
731    /// Uses the tracked venue order ID first, including a replacement ID.
732    /// The supplied `venue_order_id` is a fallback for orders without a tracked ID.
733    ///
734    /// # Errors
735    ///
736    /// Returns an error if no venue order ID is known or the cancel command cannot be sent.
737    pub async fn cancel_order(
738        &self,
739        client_order_id: ClientOrderId,
740        venue_order_id: Option<VenueOrderId>,
741    ) -> AxOrdersWsResult<i64> {
742        self.cancel_order_with_command_id(client_order_id, venue_order_id, None)
743            .await
744    }
745
746    pub(crate) async fn cancel_order_with_command_id(
747        &self,
748        client_order_id: ClientOrderId,
749        venue_order_id: Option<VenueOrderId>,
750        command_id: Option<UUID4>,
751    ) -> AxOrdersWsResult<i64> {
752        let venue_order_id = self
753            .caches
754            .orders_metadata
755            .get(&client_order_id)
756            .and_then(|metadata| metadata.venue_order_id)
757            .or(venue_order_id);
758
759        let order_id = venue_order_id.map(|v| v.to_string()).ok_or_else(|| {
760            AxOrdersWsClientError::ClientError(format!(
761                "Cannot cancel order {client_order_id}: missing venue_order_id"
762            ))
763        })?;
764
765        let request_id = self.next_request_id();
766
767        self.send_cmd(HandlerCommand::CancelOrder {
768            request_id,
769            order_id,
770            client_order_id,
771            command_id,
772        })
773        .await?;
774
775        Ok(request_id)
776    }
777
778    /// Requests open orders via WebSocket.
779    ///
780    /// # Errors
781    ///
782    /// Returns an error if the request command cannot be sent.
783    pub async fn get_open_orders(&self) -> AxOrdersWsResult<i64> {
784        let request_id = self.next_request_id();
785
786        self.send_cmd(HandlerCommand::GetOpenOrders { request_id })
787            .await?;
788
789        Ok(request_id)
790    }
791
792    /// Returns a stream of WebSocket messages.
793    ///
794    /// # Panics
795    ///
796    /// Panics if called before `connect()` or if the stream has already been taken.
797    pub fn stream(&mut self) -> impl futures_util::Stream<Item = AxOrdersWsMessage> + 'static {
798        let rx = self
799            .out_rx
800            .take()
801            .expect("Stream receiver already taken or client not connected - stream() can only be called once");
802        let mut rx = Arc::try_unwrap(rx).expect(
803            "Cannot take ownership of stream - client was cloned and other references exist",
804        );
805        async_stream::stream! {
806            while let Some(msg) = rx.recv().await {
807                yield msg;
808            }
809        }
810    }
811
812    pub(crate) fn begin_shutdown(&self) {
813        self.cancellation_token.load().cancel();
814        self.signal.store(true, Ordering::Release);
815    }
816
817    /// Disconnects the WebSocket connection gracefully.
818    pub async fn disconnect(&self) {
819        log::debug!("Disconnecting WebSocket");
820        let _ = self.send_cmd(HandlerCommand::Disconnect).await;
821    }
822
823    /// Closes the WebSocket connection and cleans up resources.
824    ///
825    /// # Errors
826    ///
827    /// Returns an error if the handler task fails or does not stop after abort.
828    pub async fn close(&mut self) -> anyhow::Result<()> {
829        let connect_lock = Arc::clone(&self.connect_lock);
830        let _guard = connect_lock.lock().await;
831        self.close_inner().await
832    }
833
834    async fn close_inner(&mut self) -> anyhow::Result<()> {
835        log::debug!("Closing WebSocket client");
836
837        // Send disconnect first to allow graceful cleanup before signal
838        self.cancellation_token.load().cancel();
839        let _ = self.send_cmd(HandlerCommand::Disconnect).await;
840        tokio::time::sleep(Duration::from_millis(50)).await;
841        self.signal.store(true, Ordering::Release);
842        self.auth_tracker.fail("Orders WebSocket disconnected");
843
844        let outcome = self
845            .task_handle
846            .finish(Duration::from_secs(2), Duration::from_secs(2))
847            .await;
848        *self.reconnect_headers.lock() = None;
849        self.out_rx = None;
850
851        if let Some(control) = &self.socket_control {
852            control.deregister();
853        }
854
855        match outcome {
856            None | Some(TaskJoinOutcome::Completed(()) | TaskJoinOutcome::Aborted) => Ok(()),
857            Some(TaskJoinOutcome::Failed(error)) => Err(anyhow::anyhow!(
858                "Architect AX orders WebSocket handler failed: {error}"
859            )),
860            Some(TaskJoinOutcome::Incomplete) => Err(anyhow::anyhow!(
861                "Architect AX orders WebSocket handler did not stop after abort"
862            )),
863        }
864    }
865
866    async fn send_cmd(&self, cmd: HandlerCommand) -> AxOrdersWsResult<()> {
867        let guard = self.cmd_tx.read().await;
868        guard
869            .send(cmd)
870            .map_err(|e| AxOrdersWsClientError::ChannelError(e.to_string()))
871    }
872}
873
874impl Drop for AxOrdersWebSocketClient {
875    fn drop(&mut self) {
876        if Arc::strong_count(&self.task_handle) == 1 && !self.task_handle.is_empty() {
877            self.cancellation_token.load().cancel();
878            self.signal.store(true, Ordering::Release);
879            self.task_handle.abort();
880
881            if let Some(control) = &self.socket_control {
882                control.deregister();
883            }
884        }
885    }
886}
887
888fn orders_ws_url(url: &str, cancel_on_disconnect: bool) -> AxOrdersWsResult<String> {
889    let (without_fragment, fragment) = url
890        .split_once('#')
891        .map_or((url, None), |(base, fragment)| (base, Some(fragment)));
892
893    let (base, query) = without_fragment
894        .split_once('?')
895        .map_or((without_fragment, None), |(base, query)| {
896            (base, Some(query))
897        });
898
899    let mut retained = Vec::new();
900
901    if let Some(query) = query {
902        for segment in query.split('&').filter(|segment| !segment.is_empty()) {
903            let pairs: Vec<(String, String)> =
904                serde_urlencoded::from_str(segment).map_err(|e| {
905                    AxOrdersWsClientError::ClientError(format!(
906                        "Invalid orders WebSocket query encoding: {e}"
907                    ))
908                })?;
909
910            if pairs
911                .first()
912                .is_some_and(|(key, _)| key == "cancel_on_disconnect")
913            {
914                continue;
915            }
916
917            retained.push(segment);
918        }
919    }
920
921    if cancel_on_disconnect {
922        retained.push("cancel_on_disconnect=true");
923    }
924
925    let mut url = base.to_string();
926    if !retained.is_empty() {
927        url.push('?');
928        url.push_str(&retained.join("&"));
929    }
930
931    if let Some(fragment) = fragment {
932        url.push('#');
933        url.push_str(fragment);
934    }
935
936    Ok(url)
937}
938
939pub(crate) fn reserve_cid_mapping(
940    caches: &OrdersCaches,
941    cid: u64,
942    client_order_id: ClientOrderId,
943) -> AxOrdersWsResult<()> {
944    match caches.cid_to_client_order_id.entry(cid) {
945        Entry::Vacant(entry) => {
946            entry.insert(client_order_id);
947            Ok(())
948        }
949        Entry::Occupied(entry) => Err(AxOrdersWsClientError::ClientError(format!(
950            "AX cid {cid} is already mapped to {}",
951            entry.get(),
952        ))),
953    }
954}
955
956#[cfg(test)]
957mod tests {
958    use std::sync::Arc;
959
960    use futures_util::StreamExt;
961    use nautilus_testkit::connection::race_command_with_publication;
962    use rstest::rstest;
963
964    use super::*;
965
966    #[rstest]
967    #[case::disabled_without_query("ws://ax/orders/ws", false, "ws://ax/orders/ws")]
968    #[case::enabled_without_query(
969        "ws://ax/orders/ws",
970        true,
971        "ws://ax/orders/ws?cancel_on_disconnect=true"
972    )]
973    #[case::disabled_removes_existing(
974        "ws://ax/orders/ws?cancel_on_disconnect=true",
975        false,
976        "ws://ax/orders/ws"
977    )]
978    #[case::enabled_replaces_existing(
979        "ws://ax/orders/ws?cancel_on_disconnect=false",
980        true,
981        "ws://ax/orders/ws?cancel_on_disconnect=true"
982    )]
983    #[case::enabled_deduplicates(
984        "ws://ax/orders/ws?cancel_on_disconnect=false&cancel_on_disconnect=true",
985        true,
986        "ws://ax/orders/ws?cancel_on_disconnect=true"
987    )]
988    #[case::preserves_raw_query_and_fragment(
989        "ws://ax/orders/ws?token=a%20b&flag&cancel_on_disconnect=false#fragment",
990        true,
991        "ws://ax/orders/ws?token=a%20b&flag&cancel_on_disconnect=true#fragment"
992    )]
993    #[case::removes_encoded_key(
994        "ws://ax/orders/ws?token=a%20b&%63ancel_on_disconnect=false#fragment",
995        false,
996        "ws://ax/orders/ws?token=a%20b#fragment"
997    )]
998    fn test_orders_ws_url(
999        #[case] url: &str,
1000        #[case] cancel_on_disconnect: bool,
1001        #[case] expected: &str,
1002    ) {
1003        assert_eq!(orders_ws_url(url, cancel_on_disconnect).unwrap(), expected);
1004    }
1005
1006    #[tokio::test]
1007    async fn command_during_sender_publication_reaches_initialized_handler() {
1008        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
1009        let addr = listener.local_addr().unwrap();
1010        let (received_tx, mut received_rx) = tokio::sync::mpsc::unbounded_channel();
1011
1012        let server = tokio::spawn(async move {
1013            let (socket, _) = listener.accept().await.unwrap();
1014            let mut socket = tokio_tungstenite::accept_async(socket).await.unwrap();
1015            while let Some(Ok(message)) = socket.next().await {
1016                if let tokio_tungstenite::tungstenite::Message::Text(text) = message {
1017                    let payload: serde_json::Value = serde_json::from_str(text.as_str()).unwrap();
1018                    let _ = received_tx.send(payload);
1019                }
1020            }
1021        });
1022
1023        let url = format!("ws://{addr}");
1024
1025        let mut ws_client = AxOrdersWebSocketClient::new(
1026            url,
1027            AccountId::from("AX-001"),
1028            TraderId::from("TRADER-001"),
1029            30,
1030            TransportBackend::default(),
1031            None,
1032        );
1033        let observer = ws_client.clone();
1034        let command = HandlerCommand::GetOpenOrders { request_id: 72 };
1035        race_command_with_publication(
1036            Arc::clone(&ws_client.cmd_tx),
1037            ws_client.connect("startup-token"),
1038            move || command,
1039            || observer.is_active(),
1040        )
1041        .await
1042        .expect("connect failed");
1043        let received = tokio::time::timeout(Duration::from_secs(2), received_rx.recv()).await;
1044        ws_client.close().await.expect("disconnect failed");
1045        server.abort();
1046
1047        let payload = received
1048            .expect("startup command must reach server")
1049            .unwrap();
1050        assert_eq!(
1051            payload,
1052            serde_json::json!({
1053                "rid": 72,
1054                "t": "o"
1055            })
1056        );
1057    }
1058
1059    #[tokio::test]
1060    async fn test_drop_aborts_handler_task() {
1061        let client = AxOrdersWebSocketClient::new(
1062            "wss://example.com/orders/ws".to_string(),
1063            AccountId::from("AX-001"),
1064            TraderId::from("TRADER-001"),
1065            30,
1066            TransportBackend::default(),
1067            None,
1068        );
1069        let (started_tx, started_rx) = tokio::sync::oneshot::channel();
1070        let (dropped_tx, dropped_rx) = tokio::sync::oneshot::channel::<()>();
1071        let handle = tokio::spawn(async move {
1072            let _dropped_tx = dropped_tx;
1073            started_tx.send(()).expect("started receiver");
1074            std::future::pending::<()>().await;
1075        });
1076
1077        client.task_handle.insert(handle);
1078        started_rx.await.expect("handler task started");
1079
1080        drop(client);
1081
1082        tokio::time::timeout(Duration::from_secs(5), dropped_rx)
1083            .await
1084            .expect("handler task future should be dropped")
1085            .expect_err("aborted task should drop its sender");
1086    }
1087
1088    #[rstest]
1089    fn test_reserve_cid_mapping_rejects_collision() {
1090        let caches = OrdersCaches::default();
1091        let cid = 123;
1092        let first_client_order_id = ClientOrderId::from("CID-123-A");
1093        let second_client_order_id = ClientOrderId::from("CID-123-B");
1094
1095        reserve_cid_mapping(&caches, cid, first_client_order_id).unwrap();
1096        let result = reserve_cid_mapping(&caches, cid, second_client_order_id);
1097
1098        assert!(matches!(
1099            result,
1100            Err(AxOrdersWsClientError::ClientError(msg))
1101                if msg == "AX cid 123 is already mapped to CID-123-A"
1102        ));
1103        assert_eq!(
1104            caches
1105                .cid_to_client_order_id
1106                .get(&cid)
1107                .map(|client_order_id| *client_order_id),
1108            Some(first_client_order_id),
1109        );
1110    }
1111}