Skip to main content

nautilus_binance/common/
dispatch.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! WebSocket dispatch state for tracked/external order routing.
17//!
18//! Orders submitted through this client and active local orders restored from the cache have their
19//! identity registered in [`WsDispatchState`]. User data stream messages route by registered identity:
20//! - Tracked orders produce typed order events (OrderAccepted, OrderFilled, etc.).
21//! - Untracked orders fall back to execution reports for reconciliation.
22//!
23//! Tracked terminal orders retain bounded replay evidence: order status reports are suppressed,
24//! and unseen late trades produce fill reports.
25
26use std::sync::Arc;
27
28use ahash::AHashSet;
29use dashmap::{DashMap, mapref::entry::Entry};
30use indexmap::IndexMap;
31use nautilus_common::cache::fifo::{FifoCache, FifoCacheMap};
32use nautilus_core::{AtomicSet, UUID4, UnixNanos};
33use nautilus_live::ExecutionEventEmitter;
34use nautilus_model::{
35    enums::{OrderSide, OrderType},
36    events::{OrderAccepted, OrderCanceled, OrderEventAny},
37    identifiers::{
38        AccountId, ClientOrderId, InstrumentId, PositionId, StrategyId, TradeId, VenueOrderId,
39    },
40    orders::{Order, OrderAny},
41    reports::{FillReport, OrderStatusReport},
42    types::{Price, Quantity},
43};
44use parking_lot::Mutex;
45use ustr::Ustr;
46
47pub(crate) const DEDUP_CAPACITY: usize = 10_000;
48
49/// The type of operation a pending WS API request represents.
50#[derive(Debug, Clone, Copy)]
51pub enum PendingOperation {
52    Place,
53    Cancel,
54    Modify,
55}
56
57/// A pending WS API request awaiting a response.
58///
59/// Stored in [`WsDispatchState::pending_requests`] after the WS client
60/// returns a request ID. When the venue responds (accepted or rejected),
61/// the pending request is removed and used to emit the correct order event.
62#[derive(Debug, Clone)]
63pub struct PendingRequest {
64    pub command_id: Option<UUID4>,
65    pub client_order_id: ClientOrderId,
66    pub venue_order_id: Option<VenueOrderId>,
67    pub operation: PendingOperation,
68}
69
70/// Outcome of a cancel-replace request, tracked by its `cancelNewClientOrderId`.
71///
72/// The cancel half's `CANCELED` report and the venue's response arrive in either
73/// order, so whichever comes second completes the picture.
74#[derive(Debug, Clone)]
75enum CancelReplaceOutcome {
76    Pending,
77    /// The cancel report arrived; withheld while the replacement is pending or succeeded.
78    ///
79    /// Parsed at that point so it can be replayed even for an order without a
80    /// dispatch identity, such as an external order.
81    Canceled(Box<OrderStatusReport>),
82    /// The venue rejected the request before any cancel report arrived.
83    Rejected,
84}
85
86/// Order identity context registered on submission or restored for an active local order.
87///
88/// Provides the strategy and instrument metadata needed to construct
89/// typed order events without accessing the cache from the async dispatch task.
90/// The quantity and quote-sizing flag retain the order's sizing intent.
91#[derive(Debug, Clone)]
92pub struct OrderIdentity {
93    pub instrument_id: InstrumentId,
94    pub strategy_id: StrategyId,
95    pub order_side: OrderSide,
96    pub order_type: OrderType,
97    pub price: Option<Price>,
98    pub quantity: Quantity,
99    pub is_quote_quantity: bool,
100    pub venue_position_id: Option<PositionId>,
101}
102
103#[derive(Debug, Clone, Copy)]
104struct AlgoOrderIds {
105    algo: VenueOrderId,
106    current: VenueOrderId,
107}
108
109/// Tracks order lifecycle state for dispatch routing.
110///
111/// Orders with a registered identity produce typed order events. Untracked orders
112/// fall back to execution reports for reconciliation. For restored orders, accepted and filled
113/// state remains available until terminal cleanup, independent of the bounded deduplication caches.
114/// Restored trade IDs remain available in the bounded terminal replay evidence after cleanup.
115#[derive(Debug)]
116pub struct WsDispatchState {
117    pub order_identities: DashMap<ClientOrderId, OrderIdentity>,
118    pub pending_requests: DashMap<String, PendingRequest>,
119    pub(crate) cancels_unresolved: Arc<AtomicSet<ClientOrderId>>,
120    pub(crate) order_lists: DashMap<ClientOrderId, OrderListIdentity>,
121    algo_order_ids: DashMap<ClientOrderId, AlgoOrderIds>,
122    order_updates: DashMap<ClientOrderId, OrderBinding>,
123    orders_restored: DashMap<ClientOrderId, RestoredOrderState>,
124    orders_terminal: Mutex<FifoCacheMap<ClientOrderId, TerminalOrderState, DEDUP_CAPACITY>>,
125    replacements: DashMap<ClientOrderId, PendingReplacement>,
126    seen_trade_ids: Arc<Mutex<FifoCache<(Ustr, i64), DEDUP_CAPACITY>>>,
127    emitted_accepted: Mutex<FifoCache<ClientOrderId, DEDUP_CAPACITY>>,
128    filled_orders: Mutex<FifoCache<ClientOrderId, DEDUP_CAPACITY>>,
129    /// Cancel-replace request IDs mapped to their `cancelNewClientOrderId`.
130    pub cancel_replace_request_ids: DashMap<String, String>,
131    cancel_replace_outcomes: Mutex<FifoCacheMap<String, CancelReplaceOutcome, DEDUP_CAPACITY>>,
132}
133
134impl Default for WsDispatchState {
135    fn default() -> Self {
136        Self {
137            order_identities: DashMap::new(),
138            pending_requests: DashMap::new(),
139            cancels_unresolved: Arc::new(AtomicSet::new()),
140            order_lists: DashMap::new(),
141            algo_order_ids: DashMap::new(),
142            order_updates: DashMap::new(),
143            orders_restored: DashMap::new(),
144            orders_terminal: Mutex::new(FifoCacheMap::new()),
145            replacements: DashMap::new(),
146            seen_trade_ids: Arc::new(Mutex::new(FifoCache::new())),
147            emitted_accepted: Mutex::new(FifoCache::new()),
148            filled_orders: Mutex::new(FifoCache::new()),
149            cancel_replace_request_ids: DashMap::new(),
150            cancel_replace_outcomes: Mutex::new(FifoCacheMap::new()),
151        }
152    }
153}
154
155impl WsDispatchState {
156    pub(crate) fn restore_order(
157        &self,
158        order: &OrderAny,
159        venue_position_id: Option<PositionId>,
160        price_precision: u8,
161    ) {
162        let cid = order.client_order_id();
163
164        let Entry::Vacant(entry) = self.order_identities.entry(cid) else {
165            return;
166        };
167
168        if self.is_terminal(&cid) {
169            return;
170        }
171
172        let accepted = order.ts_accepted().is_some();
173        self.orders_restored.insert(
174            cid,
175            RestoredOrderState {
176                trade_ids: order.trade_ids().into_iter().copied().collect(),
177                accepted,
178                filled: order.filled_qty().is_positive(),
179            },
180        );
181
182        if let Some(venue_order_id) = order.venue_order_id()
183            && !order.is_quote_quantity()
184        {
185            let current = OrderUpdate {
186                venue_order_id,
187                quantity: order.quantity(),
188                price: order
189                    .price()
190                    .unwrap_or_else(|| Price::zero(price_precision)),
191                trigger_price: order.trigger_price(),
192            };
193
194            let superseded = order
195                .venue_order_ids()
196                .into_iter()
197                .copied()
198                .filter(|id| *id != venue_order_id)
199                .collect();
200            self.order_updates.insert(
201                cid,
202                OrderBinding {
203                    current,
204                    superseded,
205                },
206            );
207        }
208
209        entry.insert(OrderIdentity {
210            instrument_id: order.instrument_id(),
211            strategy_id: order.strategy_id(),
212            order_side: order.order_side(),
213            order_type: order.order_type(),
214            price: order.price(),
215            quantity: order.quantity(),
216            is_quote_quantity: order.is_quote_quantity(),
217            venue_position_id,
218        });
219    }
220
221    pub(crate) fn restore_terminal_fills(
222        &self,
223        orders: &IndexMap<VenueOrderId, OrderStatusReport>,
224        fills: &[FillReport],
225    ) {
226        for report in orders.values() {
227            let Some(cid) = report
228                .client_order_id
229                .filter(|_| report.order_status.is_closed())
230            else {
231                continue;
232            };
233
234            if self
235                .order_updates
236                .get(&cid)
237                .is_some_and(|binding| binding.superseded.contains(&report.venue_order_id))
238            {
239                continue;
240            }
241
242            self.cleanup_terminal(cid);
243            self.clear_terminal_status_pending(&cid);
244        }
245
246        let mut seen = self.seen_trade_ids.lock();
247
248        for fill in fills {
249            let Some(order) = orders.get(&fill.venue_order_id) else {
250                continue;
251            };
252
253            if !order.order_status.is_closed()
254                || order.instrument_id != fill.instrument_id
255                || fill.ts_event > order.ts_last
256            {
257                continue;
258            }
259
260            if let Ok(trade_id) = fill.trade_id.as_str().parse::<i64>() {
261                let symbol = super::symbol::format_binance_symbol(&fill.instrument_id);
262                seen.add((Ustr::from(symbol.as_str()), trade_id));
263            }
264        }
265    }
266
267    pub fn has_emitted_accepted(&self, cid: &ClientOrderId) -> bool {
268        self.orders_restored
269            .get(cid)
270            .is_some_and(|order| order.accepted)
271            || self.order_lists.contains_key(cid)
272            || self.emitted_accepted.lock().contains(cid)
273    }
274
275    /// Marks an order as having emitted an OrderAccepted event.
276    pub fn insert_accepted(&self, cid: ClientOrderId) {
277        if let Some(mut order) = self.orders_restored.get_mut(&cid) {
278            order.accepted = true;
279        }
280
281        self.emitted_accepted.lock().add(cid);
282    }
283
284    pub fn has_filled(&self, cid: &ClientOrderId) -> bool {
285        self.orders_restored
286            .get(cid)
287            .is_some_and(|order| order.filled)
288            || self.filled_orders.lock().contains(cid)
289    }
290
291    pub(crate) fn is_order_new_stale(
292        &self,
293        cid: &ClientOrderId,
294        venue_order_id: VenueOrderId,
295    ) -> bool {
296        self.has_filled(cid)
297            && self
298                .order_updates
299                .get(cid)
300                .is_none_or(|binding| binding.current.venue_order_id == venue_order_id)
301    }
302
303    pub(crate) fn seen_trade_ids(&self) -> Arc<Mutex<FifoCache<(Ustr, i64), DEDUP_CAPACITY>>> {
304        self.seen_trade_ids.clone()
305    }
306
307    pub(crate) fn has_trade(
308        &self,
309        cid: &ClientOrderId,
310        key: &(Ustr, i64),
311        seen_trade_ids: &Mutex<FifoCache<(Ustr, i64), DEDUP_CAPACITY>>,
312    ) -> bool {
313        self.orders_restored.get(cid).is_some_and(|order| {
314            let trade_id = TradeId::new(key.1.to_string());
315            order.trade_ids.contains(&trade_id)
316        }) || self.orders_terminal.lock().get(cid).is_some_and(|order| {
317            let trade_id = TradeId::new(key.1.to_string());
318            order.trade_ids.contains(&trade_id)
319        }) || seen_trade_ids.lock().contains(key)
320    }
321
322    /// Marks an order as having received a fill.
323    pub fn insert_filled(&self, cid: ClientOrderId) {
324        if let Some(mut order) = self.orders_restored.get_mut(&cid) {
325            order.filled = true;
326        }
327
328        self.filled_orders.lock().add(cid);
329    }
330
331    /// Records the `cancelNewClientOrderId` sent with a cancel-replace request.
332    pub fn insert_cancel_replace(&self, cancel_id: String) {
333        self.cancel_replace_outcomes
334            .lock()
335            .insert(cancel_id, CancelReplaceOutcome::Pending);
336    }
337
338    /// Returns `true` when `cancel_id` belongs to a cancel-replace this client issued.
339    pub fn has_cancel_replace(&self, cancel_id: &str) -> bool {
340        self.cancel_replace_outcomes
341            .lock()
342            .contains_key(&cancel_id.to_string())
343    }
344
345    /// Records the cancel half's `CANCELED` report for a cancel-replace request.
346    ///
347    /// Returns `true` when the report must be withheld because the replacement is
348    /// pending or succeeded, and `false` when it should dispatch as a standalone
349    /// cancel because the venue already rejected the replacement or the ID is not
350    /// one this client issued.
351    pub fn on_cancel_replace_canceled(&self, cancel_id: &str, report: OrderStatusReport) -> bool {
352        let mut outcomes = self.cancel_replace_outcomes.lock();
353        let Some(outcome) = outcomes.get_mut(&cancel_id.to_string()) else {
354            return false;
355        };
356
357        match outcome {
358            CancelReplaceOutcome::Pending => {
359                *outcome = CancelReplaceOutcome::Canceled(Box::new(report));
360                true
361            }
362            CancelReplaceOutcome::Canceled(_) => true,
363            CancelReplaceOutcome::Rejected => false,
364        }
365    }
366
367    /// Records a rejected cancel-replace request.
368    ///
369    /// Returns the withheld cancel report when it already arrived, so the caller
370    /// can emit the confirmed cancellation for the original order.
371    pub fn on_cancel_replace_rejected(&self, cancel_id: &str) -> Option<OrderStatusReport> {
372        let mut outcomes = self.cancel_replace_outcomes.lock();
373        let outcome = outcomes.get_mut(&cancel_id.to_string())?;
374
375        match outcome {
376            CancelReplaceOutcome::Pending => {
377                *outcome = CancelReplaceOutcome::Rejected;
378                None
379            }
380            CancelReplaceOutcome::Canceled(report) => Some((**report).clone()),
381            CancelReplaceOutcome::Rejected => None,
382        }
383    }
384
385    pub fn insert_algo_order_id(&self, cid: ClientOrderId, venue_order_id: VenueOrderId) {
386        self.algo_order_ids.entry(cid).or_insert(AlgoOrderIds {
387            algo: venue_order_id,
388            current: venue_order_id,
389        });
390    }
391
392    /// Promotes a known Algo order to its matching-engine venue order ID.
393    ///
394    /// Returns `None` for an unknown Algo order, `Some(true)` for a new ID, and
395    /// `Some(false)` when the ID was already current.
396    pub fn promote_algo_order_id(
397        &self,
398        cid: ClientOrderId,
399        venue_order_id: VenueOrderId,
400    ) -> Option<bool> {
401        let mut ids = self.algo_order_ids.get_mut(&cid)?;
402        let changed = ids.current != venue_order_id;
403        ids.current = venue_order_id;
404        Some(changed)
405    }
406
407    /// Returns the matching-engine venue order ID for a promoted Algo order.
408    pub fn promoted_algo_order_id(&self, cid: &ClientOrderId) -> Option<VenueOrderId> {
409        self.algo_order_ids
410            .get(cid)
411            .and_then(|ids| (ids.current != ids.algo).then_some(ids.current))
412    }
413
414    /// Returns `None` for a superseded venue order ID.
415    ///
416    /// Otherwise, returns `Some(true)` for the first update or a changed venue order ID,
417    /// quantity, price, or trigger price, and `Some(false)` for unchanged values.
418    pub(crate) fn record_order_update(
419        &self,
420        cid: ClientOrderId,
421        venue_order_id: VenueOrderId,
422        quantity: Quantity,
423        price: Price,
424        trigger_price: Option<Price>,
425    ) -> Option<bool> {
426        let update = OrderUpdate {
427            venue_order_id,
428            quantity,
429            price,
430            trigger_price,
431        };
432
433        let changed = match self.order_updates.entry(cid) {
434            Entry::Occupied(mut entry) => {
435                let binding = entry.get_mut();
436                if binding.superseded.contains(&venue_order_id) {
437                    return None;
438                }
439
440                let changed = binding.current != update;
441                if binding.current.venue_order_id != venue_order_id {
442                    binding.superseded.push(binding.current.venue_order_id);
443                }
444
445                binding.current = update;
446                changed
447            }
448            Entry::Vacant(entry) => {
449                entry.insert(OrderBinding {
450                    current: update,
451                    superseded: Vec::new(),
452                });
453
454                true
455            }
456        };
457
458        self.replacements
459            .remove_if(&cid, |_, pending| pending.venue_order_id != venue_order_id);
460        Some(changed)
461    }
462
463    pub(crate) fn record_order_update_from_fill(
464        &self,
465        cid: ClientOrderId,
466        venue_order_id: VenueOrderId,
467        quantity: Quantity,
468        price: Price,
469        trigger_price: Option<Price>,
470        identity: &OrderIdentity,
471    ) -> Option<bool> {
472        if !identity.is_quote_quantity {
473            self.order_updates
474                .entry(cid)
475                .or_insert_with(|| OrderBinding {
476                    current: OrderUpdate {
477                        venue_order_id,
478                        quantity: identity.quantity,
479                        price: identity.price.unwrap_or(price),
480                        trigger_price,
481                    },
482                    superseded: Vec::new(),
483                });
484        }
485
486        self.record_order_update(cid, venue_order_id, quantity, price, trigger_price)
487    }
488
489    pub(crate) fn begin_replace(&self, cid: ClientOrderId, venue_order_id: VenueOrderId) {
490        self.replacements.insert(
491            cid,
492            PendingReplacement {
493                venue_order_id,
494                canceled: None,
495            },
496        );
497    }
498
499    pub(crate) fn defer_replace_cancel(&self, canceled: OrderCanceled) -> bool {
500        let cid = canceled.client_order_id;
501
502        if self.order_updates.get(&cid).is_some_and(|binding| {
503            canceled
504                .venue_order_id
505                .is_some_and(|venue_order_id| binding.superseded.contains(&venue_order_id))
506        }) {
507            return true;
508        }
509
510        if let Some(mut pending) = self.replacements.get_mut(&cid)
511            && Some(pending.venue_order_id) == canceled.venue_order_id
512        {
513            pending.canceled = Some(canceled);
514            return true;
515        }
516        false
517    }
518
519    pub(crate) fn reject_replace(&self, cid: ClientOrderId) -> Option<OrderCanceled> {
520        self.replacements
521            .remove(&cid)
522            .and_then(|(_, pending)| pending.canceled)
523    }
524
525    pub(crate) fn is_terminal(&self, cid: &ClientOrderId) -> bool {
526        self.orders_terminal.lock().contains_key(cid)
527    }
528
529    /// Removes active order context, retaining bounded replay evidence for tracked orders.
530    pub fn cleanup_terminal(&self, cid: ClientOrderId) {
531        if self.cancels_unresolved.contains(&cid) {
532            self.cancels_unresolved.remove(&cid);
533        }
534
535        if let Entry::Occupied(entry) = self.order_identities.entry(cid) {
536            self.mark_terminal(cid);
537            entry.remove();
538        }
539
540        self.order_lists.remove(&cid);
541        self.algo_order_ids.remove(&cid);
542        self.order_updates.remove(&cid);
543        self.orders_restored.remove(&cid);
544        self.replacements.remove(&cid);
545        self.emitted_accepted.lock().remove(&cid);
546        self.filled_orders.lock().remove(&cid);
547    }
548
549    pub(crate) fn mark_terminal(&self, cid: ClientOrderId) {
550        self.mark_terminal_status(cid, None, None);
551    }
552
553    pub(crate) fn mark_terminal_status_pending(
554        &self,
555        cid: ClientOrderId,
556        strategy_id: StrategyId,
557        qty_pending: Option<Quantity>,
558    ) {
559        self.mark_terminal_status(cid, Some(strategy_id), qty_pending);
560    }
561
562    pub(crate) fn has_terminal_qty_pending(&self, cid: &ClientOrderId) -> bool {
563        self.orders_terminal
564            .lock()
565            .get(cid)
566            .is_some_and(|order| order.qty_pending.is_some())
567    }
568
569    pub(crate) fn resolve_terminal_qty(
570        &self,
571        cid: &ClientOrderId,
572        quantity: Quantity,
573    ) -> Option<StrategyId> {
574        let mut terminal = self.orders_terminal.lock();
575        let order = terminal.get_mut(cid)?;
576        let (strategy_id, previous) = order.qty_pending.take()?;
577        (previous != quantity).then_some(strategy_id)
578    }
579
580    pub(crate) fn take_terminal_status_pending(&self, cid: &ClientOrderId) -> Option<StrategyId> {
581        let mut terminal = self.orders_terminal.lock();
582        let order = terminal.get_mut(cid)?;
583        order.strategy_pending.take()
584    }
585
586    pub(crate) fn clear_terminal_status_pending(&self, cid: &ClientOrderId) {
587        if let Some(order) = self.orders_terminal.lock().get_mut(cid) {
588            order.strategy_pending = None;
589            order.qty_pending = None;
590        }
591    }
592
593    fn mark_terminal_status(
594        &self,
595        cid: ClientOrderId,
596        strategy_pending: Option<StrategyId>,
597        qty_pending: Option<Quantity>,
598    ) {
599        let mut terminal = self.orders_terminal.lock();
600        if terminal.contains_key(&cid) {
601            return;
602        }
603
604        let trade_ids = self
605            .orders_restored
606            .remove(&cid)
607            .map_or_else(AHashSet::new, |(_, order)| order.trade_ids);
608        terminal.insert(
609            cid,
610            TerminalOrderState {
611                trade_ids,
612                strategy_pending,
613                qty_pending: strategy_pending.zip(qty_pending),
614            },
615        );
616    }
617}
618
619#[derive(Debug)]
620struct TerminalOrderState {
621    trade_ids: AHashSet<TradeId>,
622    strategy_pending: Option<StrategyId>,
623    qty_pending: Option<(StrategyId, Quantity)>,
624}
625
626#[derive(Debug)]
627struct RestoredOrderState {
628    trade_ids: AHashSet<TradeId>,
629    accepted: bool,
630    filled: bool,
631}
632
633#[derive(Debug, Clone, Copy)]
634pub(crate) struct OrderListIdentity {
635    pub order_list_id: i64,
636    pub venue_order_id: VenueOrderId,
637    pub execution_report_seen: bool,
638}
639
640#[derive(Debug)]
641struct PendingReplacement {
642    venue_order_id: VenueOrderId,
643    canceled: Option<OrderCanceled>,
644}
645
646#[derive(Debug, Clone, Copy, PartialEq, Eq)]
647struct OrderUpdate {
648    venue_order_id: VenueOrderId,
649    quantity: Quantity,
650    price: Price,
651    trigger_price: Option<Price>,
652}
653
654#[derive(Debug)]
655struct OrderBinding {
656    current: OrderUpdate,
657    superseded: Vec<VenueOrderId>,
658}
659
660/// Synthesizes and emits OrderAccepted if one has not yet been emitted.
661///
662/// Handles fast-filling orders that skip the New state on Binance.
663pub fn ensure_accepted_emitted(
664    client_order_id: ClientOrderId,
665    account_id: AccountId,
666    venue_order_id: VenueOrderId,
667    identity: &OrderIdentity,
668    emitter: &ExecutionEventEmitter,
669    state: &WsDispatchState,
670    ts_init: UnixNanos,
671) {
672    if state.has_emitted_accepted(&client_order_id) {
673        return;
674    }
675    state.insert_accepted(client_order_id);
676    let accepted = OrderAccepted::new(
677        emitter.trader_id(),
678        identity.strategy_id,
679        identity.instrument_id,
680        client_order_id,
681        venue_order_id,
682        account_id,
683        UUID4::new(),
684        ts_init,
685        ts_init,
686        false,
687    );
688    emitter.send_order_event(OrderEventAny::Accepted(accepted));
689}
690
691#[cfg(test)]
692mod tests {
693    use nautilus_model::{
694        enums::{OrderStatus, OrderType},
695        events::order::spec::{OrderFilledSpec, OrderUpdatedSpec},
696        identifiers::AccountId,
697        orders::{OrderTestBuilder, stubs::TestOrderEventStubs},
698    };
699    use rstest::rstest;
700
701    use super::*;
702
703    #[rstest]
704    #[case::submitted(false)]
705    #[case::accepted(true)]
706    fn test_restore_order_retains_identity_and_lifecycle_beyond_replay_capacity(
707        #[case] accepted: bool,
708        #[values(false, true)] quote_quantity: bool,
709    ) {
710        let order_type = if quote_quantity {
711            OrderType::Market
712        } else {
713            OrderType::Limit
714        };
715
716        let mut order = OrderTestBuilder::new(order_type)
717            .client_order_id(ClientOrderId::from("restored-active"))
718            .strategy_id(StrategyId::from("RETAINED-007"))
719            .instrument_id(InstrumentId::from("ETHUSDT.BINANCE"))
720            .side(OrderSide::Sell)
721            .quantity(Quantity::from("2.003"))
722            .price(Price::from("3456.78"))
723            .quote_quantity(quote_quantity)
724            .build();
725        let account_id = AccountId::from("BINANCE-009");
726        let submitted = TestOrderEventStubs::submitted(&order, account_id);
727        order.apply(submitted).unwrap();
728
729        if accepted {
730            let event =
731                TestOrderEventStubs::accepted(&order, account_id, VenueOrderId::from("9182"));
732            order.apply(event).unwrap();
733        }
734
735        let cid = order.client_order_id();
736        let position_id = Some(PositionId::from("ETHUSDT.BINANCE-SHORT"));
737        let state = WsDispatchState::default();
738        state.restore_order(&order, position_id, 2);
739
740        assert_eq!(state.has_emitted_accepted(&cid), accepted);
741        assert!(!state.has_filled(&cid));
742        state.insert_accepted(cid);
743        state.insert_filled(cid);
744
745        for index in 0..=DEDUP_CAPACITY {
746            let other = ClientOrderId::from(format!("other-{index}"));
747            state.insert_accepted(other);
748            state.insert_filled(other);
749        }
750
751        state.restore_order(&order, None, 2);
752
753        let identity = state.order_identities.get(&cid).unwrap().clone();
754        assert_eq!(identity.instrument_id, order.instrument_id());
755        assert_eq!(identity.strategy_id, order.strategy_id());
756        assert_eq!(identity.order_side, OrderSide::Sell);
757        assert_eq!(identity.order_type, order_type);
758        assert_eq!(
759            identity.price,
760            (!quote_quantity).then(|| Price::from("3456.78"))
761        );
762        assert_eq!(identity.quantity, Quantity::from("2.003"));
763        assert_eq!(identity.is_quote_quantity, quote_quantity);
764        assert_eq!(identity.venue_position_id, position_id);
765        assert!(state.has_emitted_accepted(&cid));
766        assert!(state.has_filled(&cid));
767
768        state.cancels_unresolved.insert(cid);
769        state.cleanup_terminal(cid);
770        assert!(!state.cancels_unresolved.contains(&cid));
771        assert!(!state.order_identities.contains_key(&cid));
772        assert!(!state.orders_restored.contains_key(&cid));
773        assert!(!state.has_emitted_accepted(&cid));
774        assert!(!state.has_filled(&cid));
775    }
776
777    #[rstest]
778    fn test_restore_market_order_seeds_zero_price_update(
779        #[values(false, true)] quote_quantity: bool,
780    ) {
781        let mut order = OrderTestBuilder::new(OrderType::Market)
782            .instrument_id(InstrumentId::from("BTCUSDT.BINANCE"))
783            .quantity(Quantity::from("0.002"))
784            .quote_quantity(quote_quantity)
785            .build();
786        let event = TestOrderEventStubs::accepted(
787            &order,
788            AccountId::from("BINANCE-001"),
789            VenueOrderId::from("312"),
790        );
791        order.apply(event).unwrap();
792        let state = WsDispatchState::default();
793        state.restore_order(&order, None, 2);
794
795        assert_eq!(
796            state.record_order_update(
797                order.client_order_id(),
798                VenueOrderId::from("312"),
799                order.quantity(),
800                Price::zero(2),
801                None
802            ),
803            Some(quote_quantity)
804        );
805    }
806
807    #[rstest]
808    fn test_terminal_eviction_preserves_active_context(
809        #[values(false, true)] status_pending: bool,
810    ) {
811        let state = WsDispatchState::default();
812        let mut order = OrderTestBuilder::new(OrderType::Limit)
813            .client_order_id(ClientOrderId::from("active-retained"))
814            .instrument_id(InstrumentId::from("BTCUSDT.BINANCE"))
815            .quantity(Quantity::from("3"))
816            .price(Price::from("50000.00"))
817            .build();
818        let accepted = TestOrderEventStubs::accepted(
819            &order,
820            AccountId::from("BINANCE-001"),
821            VenueOrderId::from("312"),
822        );
823        order.apply(accepted).unwrap();
824        state.restore_order(&order, None, 2);
825        let identity = state
826            .order_identities
827            .get(&order.client_order_id())
828            .unwrap()
829            .clone();
830
831        for index in 0..=DEDUP_CAPACITY {
832            let cid = ClientOrderId::from(format!("terminal-{index}"));
833            state.order_identities.insert(cid, identity.clone());
834            if status_pending {
835                state.mark_terminal_status_pending(
836                    cid,
837                    identity.strategy_id,
838                    Some(identity.quantity),
839                );
840            }
841
842            state.cleanup_terminal(cid);
843        }
844
845        state.cleanup_terminal(ClientOrderId::from("external"));
846        assert_eq!(state.orders_terminal.lock().len(), DEDUP_CAPACITY);
847        assert!(!state.is_terminal(&ClientOrderId::from("terminal-0")));
848        assert!(state.is_terminal(&ClientOrderId::from("terminal-1")));
849        assert_eq!(
850            state.take_terminal_status_pending(&ClientOrderId::from("terminal-0")),
851            None
852        );
853        assert_eq!(
854            state.take_terminal_status_pending(&ClientOrderId::from("terminal-1")),
855            status_pending.then_some(identity.strategy_id)
856        );
857        assert_eq!(
858            state.take_terminal_status_pending(&ClientOrderId::from("terminal-1")),
859            None
860        );
861        assert!(state.is_terminal(&ClientOrderId::from(format!("terminal-{DEDUP_CAPACITY}"))));
862        assert!(!state.is_terminal(&ClientOrderId::from("external")));
863        assert!(!state.is_terminal(&order.client_order_id()));
864        assert_eq!(state.order_identities.len(), 1);
865        assert!(state.has_emitted_accepted(&order.client_order_id()));
866        assert_eq!(
867            state.record_order_update(
868                order.client_order_id(),
869                VenueOrderId::from("312"),
870                Quantity::from("3"),
871                Price::from("50000.00"),
872                None
873            ),
874            Some(false)
875        );
876    }
877
878    #[rstest]
879    fn test_restore_order_retains_partial_fills() {
880        let mut order = OrderTestBuilder::new(OrderType::Limit)
881            .instrument_id(InstrumentId::from("BTCUSDT.BINANCE"))
882            .quantity(Quantity::from("3"))
883            .price(Price::from("50000.00"))
884            .build();
885        let accepted = TestOrderEventStubs::accepted(
886            &order,
887            AccountId::from("BINANCE-001"),
888            VenueOrderId::from("312"),
889        );
890        order.apply(accepted).unwrap();
891        let fill = OrderFilledSpec::builder()
892            .trader_id(order.trader_id())
893            .strategy_id(order.strategy_id())
894            .instrument_id(order.instrument_id())
895            .client_order_id(order.client_order_id())
896            .venue_order_id(VenueOrderId::from("312"))
897            .account_id(AccountId::from("BINANCE-001"))
898            .trade_id(TradeId::from("9182"))
899            .last_qty(Quantity::from("1"))
900            .last_px(Price::from("50000.00"))
901            .build();
902        order.apply(OrderEventAny::Filled(fill)).unwrap();
903        let state = WsDispatchState::default();
904        state.restore_order(&order, None, 2);
905
906        assert!(state.has_emitted_accepted(&order.client_order_id()));
907        assert!(state.has_filled(&order.client_order_id()));
908        let seen_trade_ids = Mutex::new(FifoCache::new());
909        assert!(state.has_trade(
910            &order.client_order_id(),
911            &(Ustr::from("BTCUSDT"), 9182),
912            &seen_trade_ids
913        ));
914        assert!(!state.has_trade(
915            &order.client_order_id(),
916            &(Ustr::from("BTCUSDT"), 9183),
917            &seen_trade_ids
918        ));
919        state.mark_terminal(order.client_order_id());
920        state.cleanup_terminal(order.client_order_id());
921        state.cleanup_terminal(order.client_order_id());
922        assert!(state.is_terminal(&order.client_order_id()));
923        state.restore_order(&order, None, 2);
924        assert!(
925            !state
926                .order_identities
927                .contains_key(&order.client_order_id())
928        );
929        assert!(state.has_trade(
930            &order.client_order_id(),
931            &(Ustr::from("BTCUSDT"), 9182),
932            &seen_trade_ids
933        ));
934        assert!(!state.has_trade(
935            &order.client_order_id(),
936            &(Ustr::from("BTCUSDT"), 9183),
937            &seen_trade_ids
938        ));
939    }
940
941    #[rstest]
942    fn test_restore_order_same_shape_replacement_updates_venue_id() {
943        let mut order = OrderTestBuilder::new(OrderType::Limit)
944            .instrument_id(InstrumentId::from("BTCUSDT.BINANCE"))
945            .quantity(Quantity::from("3"))
946            .price(Price::from("50000.00"))
947            .build();
948        let account_id = AccountId::from("BINANCE-001");
949        let old_id = VenueOrderId::from("312");
950        let current_id = VenueOrderId::from("313");
951        let accepted = TestOrderEventStubs::accepted(&order, account_id, old_id);
952        order.apply(accepted).unwrap();
953        let state = WsDispatchState::default();
954        state.restore_order(&order, None, 2);
955
956        let canceled = OrderCanceled::new(
957            order.trader_id(),
958            order.strategy_id(),
959            order.instrument_id(),
960            order.client_order_id(),
961            UUID4::new(),
962            UnixNanos::default(),
963            UnixNanos::default(),
964            false,
965            Some(current_id),
966            Some(account_id),
967            None,
968        );
969        assert!(!state.defer_replace_cancel(canceled));
970        assert_eq!(
971            state.record_order_update(
972                order.client_order_id(),
973                current_id,
974                order.quantity(),
975                order.price().unwrap(),
976                None
977            ),
978            Some(true)
979        );
980        assert_eq!(
981            state.record_order_update(
982                order.client_order_id(),
983                current_id,
984                order.quantity(),
985                order.price().unwrap(),
986                None
987            ),
988            Some(false)
989        );
990
991        let stale_canceled = OrderCanceled::new(
992            order.trader_id(),
993            order.strategy_id(),
994            order.instrument_id(),
995            order.client_order_id(),
996            UUID4::new(),
997            UnixNanos::default(),
998            UnixNanos::default(),
999            false,
1000            Some(old_id),
1001            Some(account_id),
1002            None,
1003        );
1004        assert!(state.defer_replace_cancel(stale_canceled));
1005        assert!(!state.defer_replace_cancel(canceled));
1006    }
1007
1008    #[rstest]
1009    fn test_restore_order_retains_superseded_venue_ids() {
1010        let mut order = OrderTestBuilder::new(OrderType::Limit)
1011            .instrument_id(InstrumentId::from("BTCUSDT.BINANCE"))
1012            .quantity(Quantity::from("3"))
1013            .price(Price::from("50000.00"))
1014            .build();
1015        let account_id = AccountId::from("BINANCE-001");
1016        let old_id = VenueOrderId::from("312");
1017        let current_id = VenueOrderId::from("313");
1018        let unknown_id = VenueOrderId::from("314");
1019        let accepted = TestOrderEventStubs::accepted(&order, account_id, old_id);
1020        order.apply(accepted).unwrap();
1021        let updated = OrderUpdatedSpec::builder()
1022            .trader_id(order.trader_id())
1023            .strategy_id(order.strategy_id())
1024            .instrument_id(order.instrument_id())
1025            .client_order_id(order.client_order_id())
1026            .quantity(order.quantity())
1027            .price(order.price().unwrap())
1028            .venue_order_id(current_id)
1029            .account_id(account_id)
1030            .build();
1031        order.apply(OrderEventAny::Updated(updated)).unwrap();
1032        let state = WsDispatchState::default();
1033        state.restore_order(&order, None, 2);
1034
1035        for (venue_order_id, suppressed) in
1036            [(old_id, true), (current_id, false), (unknown_id, false)]
1037        {
1038            let canceled = OrderCanceled::new(
1039                order.trader_id(),
1040                order.strategy_id(),
1041                order.instrument_id(),
1042                order.client_order_id(),
1043                UUID4::new(),
1044                UnixNanos::default(),
1045                UnixNanos::default(),
1046                false,
1047                Some(venue_order_id),
1048                Some(account_id),
1049                None,
1050            );
1051            assert_eq!(state.defer_replace_cancel(canceled), suppressed);
1052        }
1053
1054        state.begin_replace(order.client_order_id(), current_id);
1055
1056        let pending = OrderCanceled::new(
1057            order.trader_id(),
1058            order.strategy_id(),
1059            order.instrument_id(),
1060            order.client_order_id(),
1061            UUID4::new(),
1062            UnixNanos::default(),
1063            UnixNanos::default(),
1064            false,
1065            Some(current_id),
1066            Some(account_id),
1067            None,
1068        );
1069        assert!(state.defer_replace_cancel(pending));
1070        assert_eq!(
1071            state.record_order_update(
1072                order.client_order_id(),
1073                old_id,
1074                Quantity::from("2"),
1075                Price::from("49000.00"),
1076                None
1077            ),
1078            None
1079        );
1080        assert_eq!(state.reject_replace(order.client_order_id()), Some(pending));
1081
1082        let mut report = OrderStatusReport::new(
1083            account_id,
1084            order.instrument_id(),
1085            Some(order.client_order_id()),
1086            old_id,
1087            Some(order.order_side()),
1088            order.order_type(),
1089            order.time_in_force(),
1090            OrderStatus::Canceled,
1091            order.quantity(),
1092            Quantity::from("0"),
1093            UnixNanos::default(),
1094            UnixNanos::default(),
1095            UnixNanos::default(),
1096            None,
1097        );
1098        state.restore_terminal_fills(&IndexMap::from([(old_id, report.clone())]), &[]);
1099        assert!(!state.is_terminal(&order.client_order_id()));
1100        assert!(
1101            state
1102                .order_identities
1103                .contains_key(&order.client_order_id())
1104        );
1105        report.venue_order_id = current_id;
1106        state.restore_terminal_fills(&IndexMap::from([(current_id, report)]), &[]);
1107        assert!(state.is_terminal(&order.client_order_id()));
1108        assert!(
1109            !state
1110                .order_identities
1111                .contains_key(&order.client_order_id())
1112        );
1113    }
1114}