Skip to main content

nautilus_derive/websocket/
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//! Shared state for the Derive execution WebSocket dispatch loop.
17//!
18//! Holds instrument precision, identity context for submitted orders and active
19//! orders restored from the cache, and the cross-stream deduplication gates that
20//! keep replay frames and concurrent `.orders` / `.trades` updates from emitting
21//! duplicate events.
22//!
23//! Tracked orders (those whose identity was registered at submission or restored)
24//! produce proper order events (`OrderAccepted`, `OrderFilled`, `OrderCanceled`,
25//! `OrderExpired`, `OrderRejected`). Untracked frames fall back to execution
26//! reports for downstream reconciliation.
27
28use std::sync::Arc;
29
30use ahash::{AHashMap, AHashSet};
31use nautilus_common::cache::fifo::{FifoCache, FifoCacheMap};
32use nautilus_model::{
33    enums::{OrderSide, OrderStatus, OrderType},
34    events::OrderEventAny,
35    identifiers::{ClientOrderId, InstrumentId, StrategyId, TradeId, VenueOrderId},
36    orders::{Order, OrderAny},
37    types::{Price, Quantity},
38};
39use parking_lot::{Mutex, ReentrantMutex, ReentrantMutexGuard};
40use rust_decimal::Decimal;
41
42use crate::http::models::{DeriveReplaceResult, DeriveTrade};
43
44/// Capacity for the cross-source trade-id dedup cache. Sized to cover any
45/// reconciliation lookback window plausible for live trading.
46pub const TRADE_DEDUP_CAPACITY: usize = 4_096;
47
48/// Capacity for the per-order accepted / filled dedup caches. Tracks active
49/// and recently-terminal orders so reconnect replays do not re-emit lifecycle
50/// events; need only span the live-stream replay window plus a margin.
51pub const ORDER_DEDUP_CAPACITY: usize = 1_024;
52
53/// Order identity captured at submission or restored so the dispatch task can build
54/// proper order events without consulting the cache.
55#[derive(Debug, Clone, Copy, PartialEq, Eq)]
56pub struct OrderIdentity {
57    pub instrument_id: InstrumentId,
58    pub strategy_id: StrategyId,
59    pub order_side: OrderSide,
60    pub order_type: OrderType,
61}
62
63#[derive(Debug, Clone)]
64pub(crate) struct ReplaceCompletion {
65    pub old_venue_order_id: VenueOrderId,
66    pub nonce: u64,
67    pub identity: OrderIdentity,
68    pub result: Result<DeriveReplaceResult, String>,
69    pub trades: Vec<DeriveTrade>,
70}
71
72/// Shared dispatch state for the Derive WS execution loop.
73///
74/// Instrument precision populates from instrument definitions and governs
75/// execution report values. `order_identities` populates on submission and from
76/// active cached orders before streaming, and is consulted by both the `.orders`
77/// and `.trades` dispatch paths to decide whether a frame belongs to a tracked or external
78/// order. `pending_modifies` and `bound_venue_order_ids` track the in-flight
79/// and current venue order id of a `private/replace` so the dispatch suppresses
80/// events for the superseded leg.
81#[derive(Debug)]
82pub struct WsDispatchState {
83    subaccount_id: u64,
84    delivery: ReentrantMutex<()>,
85    order_identities: Mutex<AHashMap<ClientOrderId, OrderIdentity>>,
86    instrument_precisions: Mutex<AHashMap<InstrumentId, (u8, u8)>>,
87    emitted_accepted: Mutex<AHashSet<ClientOrderId>>,
88    triggers_active: Mutex<AHashSet<ClientOrderId>>,
89    terminal_orders: Mutex<FifoCacheMap<ClientOrderId, OrderBinding, ORDER_DEDUP_CAPACITY>>,
90    terminal_revision: Mutex<Arc<()>>,
91    order_shapes: Mutex<AHashMap<ClientOrderId, OrderShape>>,
92    emitted_canceled: Mutex<FifoCache<ClientOrderId, ORDER_DEDUP_CAPACITY>>,
93    filled_orders: Mutex<FifoCache<ClientOrderId, ORDER_DEDUP_CAPACITY>>,
94    emitted_trades: Mutex<FifoCache<TradeId, TRADE_DEDUP_CAPACITY>>,
95    bound_venue_order_ids: Mutex<AHashMap<ClientOrderId, VenueOrderId>>,
96    pending_modifies: Mutex<AHashMap<ClientOrderId, VenueOrderId>>,
97    modify_nonces: Mutex<AHashMap<ClientOrderId, u64>>,
98    deferred_trades: Mutex<AHashMap<ClientOrderId, Vec<DeriveTrade>>>,
99    undelivered_trades: Mutex<AHashMap<(String, String), DeriveTrade>>,
100    replace_completions: Mutex<AHashMap<ClientOrderId, ReplaceCompletion>>,
101    venue_order_legs: Mutex<AHashMap<ClientOrderId, AHashSet<VenueOrderId>>>,
102    modify_targets: Mutex<AHashMap<ClientOrderId, (Quantity, Option<Price>)>>,
103    unresolved_bindings: Mutex<AHashMap<ClientOrderId, AHashSet<VenueOrderId>>>,
104}
105
106impl WsDispatchState {
107    /// Creates dispatch state scoped to one native Derive subaccount.
108    #[must_use]
109    pub fn new(subaccount_id: u64) -> Self {
110        Self {
111            subaccount_id,
112            delivery: Default::default(),
113            order_identities: Default::default(),
114            instrument_precisions: Default::default(),
115            emitted_accepted: Default::default(),
116            triggers_active: Default::default(),
117            terminal_orders: Default::default(),
118            terminal_revision: Default::default(),
119            order_shapes: Default::default(),
120            emitted_canceled: Default::default(),
121            filled_orders: Default::default(),
122            emitted_trades: Default::default(),
123            bound_venue_order_ids: Default::default(),
124            pending_modifies: Default::default(),
125            modify_nonces: Default::default(),
126            deferred_trades: Default::default(),
127            undelivered_trades: Default::default(),
128            replace_completions: Default::default(),
129            venue_order_legs: Default::default(),
130            modify_targets: Default::default(),
131            unresolved_bindings: Default::default(),
132        }
133    }
134
135    pub(crate) const fn subaccount_id(&self) -> u64 {
136        self.subaccount_id
137    }
138
139    pub(crate) fn owns_subaccount(&self, subaccount_id: i64) -> bool {
140        u64::try_from(subaccount_id).ok() == Some(self.subaccount_id)
141    }
142
143    pub(crate) fn delivery_guard(&self) -> ReentrantMutexGuard<'_, ()> {
144        self.delivery.lock()
145    }
146
147    /// Records price and size precision for execution report parsing.
148    pub(crate) fn register_instrument_precision(
149        &self,
150        instrument_id: InstrumentId,
151        price_precision: u8,
152        size_precision: u8,
153    ) {
154        self.instrument_precisions
155            .lock()
156            .insert(instrument_id, (price_precision, size_precision));
157    }
158
159    /// Returns price and size precision for an instrument, when registered.
160    #[must_use]
161    pub(crate) fn instrument_precision(&self, instrument_id: &InstrumentId) -> Option<(u8, u8)> {
162        self.instrument_precisions
163            .lock()
164            .get(instrument_id)
165            .copied()
166    }
167
168    /// Registers an order identity captured at submission so subsequent WS
169    /// frames for the same client_order_id resolve to the tracked path.
170    pub fn register_identity(&self, client_order_id: ClientOrderId, identity: OrderIdentity) {
171        self.terminal_orders.lock().remove(&client_order_id);
172        self.order_identities
173            .lock()
174            .insert(client_order_id, identity);
175    }
176
177    /// Returns the registered identity for a client order, when one was
178    /// captured at submission time.
179    #[must_use]
180    pub fn identity(&self, client_order_id: &ClientOrderId) -> Option<OrderIdentity> {
181        self.order_identities.lock().get(client_order_id).copied()
182    }
183
184    pub(crate) fn restore_order(&self, order: &OrderAny) {
185        let _delivery = self.delivery_guard();
186        let client_order_id = order.client_order_id();
187        if self.identity(&client_order_id).is_some()
188            || self.is_terminal(&client_order_id, order.instrument_id())
189        {
190            return;
191        }
192
193        self.register_identity(
194            client_order_id,
195            OrderIdentity {
196                instrument_id: order.instrument_id(),
197                strategy_id: order.strategy_id(),
198                order_side: order.order_side(),
199                order_type: order.order_type(),
200            },
201        );
202
203        let quantity = order.filled_qty() + order.leaves_qty();
204        self.order_shapes.lock().insert(
205            client_order_id,
206            OrderShape {
207                quantity,
208                price: order.price(),
209                filled_qty: order.filled_qty().as_decimal(),
210                filled_qty_expected: quantity.as_decimal(),
211            },
212        );
213
214        if let Some(venue_order_id) = order.venue_order_id() {
215            self.record_venue_order_id(client_order_id, venue_order_id);
216            if order.status() == OrderStatus::PendingUpdate {
217                self.mark_pending_modify(client_order_id, venue_order_id);
218            }
219        }
220
221        let mut current_filled = false;
222
223        for event in order.events() {
224            match event {
225                OrderEventAny::Accepted(accepted) => {
226                    self.mark_accepted(client_order_id);
227                    self.record_venue_leg(client_order_id, accepted.venue_order_id);
228                }
229                OrderEventAny::Updated(updated) => {
230                    if let Some(venue_order_id) = updated.venue_order_id {
231                        self.record_venue_leg(client_order_id, venue_order_id);
232                    }
233                }
234                OrderEventAny::Filled(fill) => {
235                    self.record_venue_leg(client_order_id, fill.venue_order_id);
236                    self.mark_accepted(client_order_id);
237                    self.check_and_insert_trade(fill.trade_id);
238                    current_filled |= order.venue_order_id() == Some(fill.venue_order_id);
239                }
240                _ => {}
241            }
242        }
243
244        if order.is_triggered() == Some(true) || (order.is_triggered().is_some() && current_filled)
245        {
246            self.mark_trigger_active(client_order_id);
247        }
248    }
249
250    /// Retires active ownership and preserves bounded terminal replay state.
251    pub fn forget(&self, client_order_id: &ClientOrderId) {
252        let _delivery = self.delivery_guard();
253
254        if let Some(binding) = self.order_binding(client_order_id) {
255            let mut terminal = self.terminal_orders.lock();
256            if terminal.len() == terminal.capacity() && !terminal.contains_key(client_order_id) {
257                *self.terminal_revision.lock() = Arc::new(());
258            }
259
260            terminal.insert(*client_order_id, binding);
261        }
262
263        self.order_identities.lock().remove(client_order_id);
264        self.order_shapes.lock().remove(client_order_id);
265        self.emitted_accepted.lock().remove(client_order_id);
266        self.triggers_active.lock().remove(client_order_id);
267        self.bound_venue_order_ids.lock().remove(client_order_id);
268        self.venue_order_legs.lock().remove(client_order_id);
269        self.pending_modifies.lock().remove(client_order_id);
270        self.modify_nonces.lock().remove(client_order_id);
271        self.modify_targets.lock().remove(client_order_id);
272        self.unresolved_bindings.lock().remove(client_order_id);
273    }
274
275    pub(crate) fn mark_trigger_active(&self, client_order_id: ClientOrderId) {
276        self.triggers_active.lock().insert(client_order_id);
277    }
278
279    pub(crate) fn trigger_active(&self, client_order_id: &ClientOrderId) -> bool {
280        let _delivery = self.delivery_guard();
281        self.triggers_active.lock().contains(client_order_id)
282    }
283
284    pub(crate) fn take_identity(&self, client_order_id: &ClientOrderId) -> Option<OrderIdentity> {
285        let identity = self.identity(client_order_id);
286        if identity.is_some() {
287            self.forget(client_order_id);
288        }
289
290        identity
291    }
292
293    pub(crate) fn terminal_revision(&self) -> Arc<()> {
294        Arc::clone(&self.terminal_revision.lock())
295    }
296
297    pub(crate) fn known_instrument(&self, client_order_id: &ClientOrderId) -> Option<InstrumentId> {
298        self.identity(client_order_id)
299            .map(|identity| identity.instrument_id)
300            .or_else(|| {
301                self.terminal_orders
302                    .lock()
303                    .get(client_order_id)
304                    .map(|binding| binding.identity.instrument_id)
305            })
306    }
307
308    pub(crate) fn is_terminal(
309        &self,
310        client_order_id: &ClientOrderId,
311        instrument_id: InstrumentId,
312    ) -> bool {
313        self.terminal_orders
314            .lock()
315            .get(client_order_id)
316            .is_some_and(|binding| binding.identity.instrument_id == instrument_id)
317    }
318
319    pub(crate) fn record_order_shape(
320        &self,
321        client_order_id: ClientOrderId,
322        quantity: Quantity,
323        price: Option<Price>,
324    ) {
325        self.order_shapes
326            .lock()
327            .entry(client_order_id)
328            .and_modify(|entry| {
329                entry.quantity = quantity;
330                entry.price = price;
331                entry.filled_qty_expected = quantity.as_decimal();
332            })
333            .or_insert(OrderShape {
334                quantity,
335                price,
336                filled_qty: Decimal::ZERO,
337                filled_qty_expected: quantity.as_decimal(),
338            });
339    }
340
341    pub(crate) fn order_shape(
342        &self,
343        client_order_id: &ClientOrderId,
344    ) -> Option<(Quantity, Option<Price>)> {
345        self.order_shapes
346            .lock()
347            .get(client_order_id)
348            .map(|entry| (entry.quantity, entry.price))
349    }
350
351    pub(crate) fn record_fill(&self, client_order_id: ClientOrderId, quantity: Quantity) {
352        let _delivery = self.delivery_guard();
353
354        let complete = self
355            .order_shapes
356            .lock()
357            .get_mut(&client_order_id)
358            .is_some_and(|entry| {
359                entry.filled_qty += quantity.as_decimal();
360                entry.filled_qty >= entry.filled_qty_expected
361            });
362
363        if complete
364            && self.pending_modify(&client_order_id).is_none()
365            && !self.binding_unresolved(&client_order_id)
366        {
367            self.forget(&client_order_id);
368        }
369    }
370
371    pub(crate) fn record_canceled(
372        &self,
373        client_order_id: ClientOrderId,
374        quantity: Quantity,
375        filled_qty: Quantity,
376    ) {
377        let _delivery = self.delivery_guard();
378
379        let pending_fills = self
380            .order_shapes
381            .lock()
382            .get_mut(&client_order_id)
383            .is_some_and(|entry| {
384                // Native amounts cover this leg; the logical quantity includes prior legs' fills
385                entry.filled_qty_expected =
386                    entry.quantity.as_decimal() - quantity.as_decimal() + filled_qty.as_decimal();
387                entry.filled_qty < entry.filled_qty_expected
388            });
389
390        if !pending_fills {
391            self.forget(&client_order_id);
392        }
393    }
394
395    /// Records the venue order id currently bound to a tracked client order.
396    pub fn record_venue_order_id(
397        &self,
398        client_order_id: ClientOrderId,
399        venue_order_id: VenueOrderId,
400    ) {
401        self.record_venue_leg(client_order_id, venue_order_id);
402        self.bound_venue_order_ids
403            .lock()
404            .insert(client_order_id, venue_order_id);
405    }
406
407    pub(crate) fn record_venue_leg(
408        &self,
409        client_order_id: ClientOrderId,
410        venue_order_id: VenueOrderId,
411    ) {
412        self.venue_order_legs
413            .lock()
414            .entry(client_order_id)
415            .or_default()
416            .insert(venue_order_id);
417    }
418
419    pub(crate) fn knows_venue_leg(
420        &self,
421        client_order_id: &ClientOrderId,
422        venue_order_id: VenueOrderId,
423    ) -> bool {
424        self.venue_order_legs
425            .lock()
426            .get(client_order_id)
427            .is_some_and(|legs| legs.contains(&venue_order_id))
428    }
429
430    pub(crate) fn venue_order_legs(&self, client_order_id: &ClientOrderId) -> Vec<VenueOrderId> {
431        self.venue_order_legs
432            .lock()
433            .get(client_order_id)
434            .map_or_default(|legs| legs.iter().copied().collect())
435    }
436
437    pub(crate) fn order_binding(&self, client_order_id: &ClientOrderId) -> Option<OrderBinding> {
438        let _delivery = self.delivery_guard();
439        self.identity(client_order_id)
440            .map(|identity| {
441                let mut venue_order_legs = self.venue_order_legs(client_order_id);
442                venue_order_legs.sort_unstable();
443
444                OrderBinding {
445                    identity,
446                    venue_order_id: self.bound_venue_order_id(client_order_id),
447                    venue_order_legs,
448                }
449            })
450            .or_else(|| self.terminal_orders.lock().get(client_order_id).cloned())
451    }
452
453    pub(crate) fn defer_binding(
454        &self,
455        client_order_id: ClientOrderId,
456        venue_order_id: VenueOrderId,
457    ) {
458        self.unresolved_bindings
459            .lock()
460            .entry(client_order_id)
461            .or_default()
462            .insert(venue_order_id);
463    }
464
465    pub(crate) fn binding_unresolved(&self, client_order_id: &ClientOrderId) -> bool {
466        self.unresolved_bindings
467            .lock()
468            .get(client_order_id)
469            .is_some_and(|legs| {
470                legs.iter()
471                    .any(|venue_order_id| !self.knows_venue_leg(client_order_id, *venue_order_id))
472            })
473    }
474
475    pub(crate) fn unresolved_client_order_id(
476        &self,
477        instrument_id: Option<InstrumentId>,
478    ) -> Option<ClientOrderId> {
479        let mut ids: Vec<_> = self.unresolved_bindings.lock().keys().copied().collect();
480        ids.extend(self.pending_modifies.lock().keys().copied());
481        ids.sort_unstable();
482        ids.dedup();
483        ids.into_iter().find(|client_order_id| {
484            self.identity(client_order_id).is_some_and(|identity| {
485                instrument_id.is_none_or(|instrument_id| identity.instrument_id == instrument_id)
486            }) && (self.binding_unresolved(client_order_id)
487                || self.pending_modify(client_order_id).is_some())
488        })
489    }
490
491    pub(crate) fn has_active_orders(&self) -> bool {
492        !self.order_identities.lock().is_empty()
493    }
494
495    pub(crate) fn defer_trade(&self, client_order_id: ClientOrderId, trade: DeriveTrade) {
496        let mut deferred = self.deferred_trades.lock();
497        let trades = deferred.entry(client_order_id).or_default();
498        if !trades.iter().any(|existing| {
499            existing.trade_id == trade.trade_id && existing.order_id == trade.order_id
500        }) {
501            trades.push(trade);
502        }
503    }
504
505    pub(crate) fn take_deferred_trades(&self, client_order_id: &ClientOrderId) -> Vec<DeriveTrade> {
506        self.deferred_trades
507            .lock()
508            .remove(client_order_id)
509            .unwrap_or_default()
510    }
511
512    pub(crate) fn retain_trade(&self, trade: DeriveTrade) {
513        self.undelivered_trades
514            .lock()
515            .insert((trade.order_id.clone(), trade.trade_id.clone()), trade);
516    }
517
518    pub(crate) fn take_undelivered_trades(&self) -> Vec<DeriveTrade> {
519        let mut trades: Vec<_> = self
520            .undelivered_trades
521            .lock()
522            .drain()
523            .map(|(_, trade)| trade)
524            .collect();
525        trades.sort_unstable_by(|a, b| {
526            (a.timestamp, &a.order_id, &a.trade_id).cmp(&(b.timestamp, &b.order_id, &b.trade_id))
527        });
528
529        trades
530    }
531
532    pub(crate) fn record_replace_completion(
533        &self,
534        client_order_id: ClientOrderId,
535        completion: ReplaceCompletion,
536    ) {
537        self.replace_completions
538            .lock()
539            .insert(client_order_id, completion);
540    }
541
542    pub(crate) fn replace_completions(&self) -> Vec<(ClientOrderId, ReplaceCompletion)> {
543        let mut completions: Vec<_> = self
544            .replace_completions
545            .lock()
546            .iter()
547            .map(|(cid, completion)| (*cid, completion.clone()))
548            .collect();
549        completions.sort_unstable_by_key(|(cid, _)| *cid);
550        completions
551    }
552
553    pub(crate) fn clear_replace_completion(&self, client_order_id: &ClientOrderId) {
554        self.replace_completions.lock().remove(client_order_id);
555    }
556
557    /// Returns the venue order id currently bound to a tracked client order.
558    #[must_use]
559    pub fn bound_venue_order_id(&self, client_order_id: &ClientOrderId) -> Option<VenueOrderId> {
560        self.bound_venue_order_ids
561            .lock()
562            .get(client_order_id)
563            .copied()
564    }
565
566    /// Records the old venue order id of an in-flight `private/replace`, set
567    /// before the request so the cancel leg is suppressed.
568    pub fn mark_pending_modify(
569        &self,
570        client_order_id: ClientOrderId,
571        old_venue_order_id: VenueOrderId,
572    ) -> bool {
573        let mut pending = self.pending_modifies.lock();
574        if pending.contains_key(&client_order_id) {
575            return false;
576        }
577
578        pending.insert(client_order_id, old_venue_order_id);
579        true
580    }
581
582    /// Clears the in-flight modify marker once the replace resolves.
583    pub fn clear_pending_modify(&self, client_order_id: &ClientOrderId) {
584        self.pending_modifies.lock().remove(client_order_id);
585        self.modify_nonces.lock().remove(client_order_id);
586        self.modify_targets.lock().remove(client_order_id);
587    }
588
589    pub(crate) fn record_modify_nonce(&self, client_order_id: ClientOrderId, nonce: u64) {
590        self.modify_nonces.lock().insert(client_order_id, nonce);
591    }
592
593    pub(crate) fn modify_nonce(&self, client_order_id: &ClientOrderId) -> Option<u64> {
594        self.modify_nonces.lock().get(client_order_id).copied()
595    }
596
597    pub(crate) fn record_modify_target(
598        &self,
599        client_order_id: ClientOrderId,
600        quantity: Quantity,
601        price: Option<Price>,
602    ) {
603        self.modify_targets
604            .lock()
605            .insert(client_order_id, (quantity, price));
606    }
607
608    pub(crate) fn modify_target(
609        &self,
610        client_order_id: &ClientOrderId,
611    ) -> Option<(Quantity, Option<Price>)> {
612        self.modify_targets.lock().get(client_order_id).copied()
613    }
614
615    pub(crate) fn take_modify_target(
616        &self,
617        client_order_id: &ClientOrderId,
618    ) -> Option<(Quantity, Option<Price>)> {
619        self.modify_targets.lock().remove(client_order_id)
620    }
621
622    /// Returns the old venue order id of an in-flight modify, when one is set.
623    #[must_use]
624    pub fn pending_modify(&self, client_order_id: &ClientOrderId) -> Option<VenueOrderId> {
625        self.pending_modifies.lock().get(client_order_id).copied()
626    }
627
628    /// Rebinds an in-flight modify when a frame for its replacement arrives
629    /// before the `private/replace` response.
630    pub fn bind_incoming_modify(
631        &self,
632        client_order_id: ClientOrderId,
633        venue_order_id: VenueOrderId,
634        terminal: bool,
635    ) -> bool {
636        let mut pending = self.pending_modifies.lock();
637
638        let Some(old_venue_order_id) = pending.get(&client_order_id).copied() else {
639            return false;
640        };
641
642        if old_venue_order_id == venue_order_id {
643            return false;
644        }
645
646        let mut bound = self.bound_venue_order_ids.lock();
647        if bound
648            .get(&client_order_id)
649            .is_some_and(|current| *current != old_venue_order_id)
650        {
651            return false;
652        }
653
654        bound.insert(client_order_id, venue_order_id);
655        if terminal {
656            pending.remove(&client_order_id);
657        }
658
659        true
660    }
661
662    /// Atomically claims a pending modify for its RPC response, optionally
663    /// rebinding the replacement venue order id before clearing the marker.
664    /// Returns `false` when an incoming terminal frame already resolved it.
665    pub fn take_pending_modify(
666        &self,
667        client_order_id: &ClientOrderId,
668        old_venue_order_id: VenueOrderId,
669        new_venue_order_id: Option<VenueOrderId>,
670    ) -> bool {
671        let mut pending = self.pending_modifies.lock();
672        if pending.get(client_order_id) != Some(&old_venue_order_id) {
673            return false;
674        }
675
676        if let Some(new_venue_order_id) = new_venue_order_id {
677            self.record_venue_leg(*client_order_id, new_venue_order_id);
678            self.bound_venue_order_ids
679                .lock()
680                .insert(*client_order_id, new_venue_order_id);
681        }
682
683        pending.remove(client_order_id);
684        self.modify_nonces.lock().remove(client_order_id);
685        true
686    }
687
688    /// Returns `true` when an `OrderAccepted` has already been emitted for
689    /// this client order in the current process lifetime.
690    #[must_use]
691    pub fn contains_accepted(&self, client_order_id: &ClientOrderId) -> bool {
692        self.emitted_accepted.lock().contains(client_order_id)
693    }
694
695    /// Records that `OrderAccepted` has been emitted for this client order.
696    /// Returns `true` when the marker was already present (duplicate).
697    pub fn mark_accepted(&self, client_order_id: ClientOrderId) -> bool {
698        !self.emitted_accepted.lock().insert(client_order_id)
699    }
700
701    pub(crate) fn contains_canceled(&self, client_order_id: &ClientOrderId) -> bool {
702        self.emitted_canceled.lock().contains(client_order_id)
703    }
704
705    /// Records that `OrderCanceled` has been emitted for this client order.
706    /// Returns `true` when the marker was already present (duplicate).
707    pub fn mark_canceled(&self, client_order_id: ClientOrderId) -> bool {
708        let mut cache = self.emitted_canceled.lock();
709        if cache.contains(&client_order_id) {
710            return true;
711        }
712
713        cache.add(client_order_id);
714        false
715    }
716
717    /// Returns `true` when this client order has reached a terminal filled
718    /// state, used to suppress stale Accepted frames replayed on reconnect.
719    #[must_use]
720    pub fn contains_filled(&self, client_order_id: &ClientOrderId) -> bool {
721        self.filled_orders.lock().contains(client_order_id)
722    }
723
724    /// Marks the client order as terminally filled. Idempotent.
725    pub fn mark_filled(&self, client_order_id: ClientOrderId) {
726        let mut cache = self.filled_orders.lock();
727        if !cache.contains(&client_order_id) {
728            cache.add(client_order_id);
729        }
730    }
731
732    /// Inserts the trade id atomically. Returns `true` when the id was
733    /// already present (i.e., this fill should be skipped as a duplicate).
734    pub fn check_and_insert_trade(&self, trade_id: TradeId) -> bool {
735        let mut cache = self.emitted_trades.lock();
736        if cache.contains(&trade_id) {
737            return true;
738        }
739
740        cache.add(trade_id);
741        false
742    }
743
744    /// Returns `true` when this trade id has already been seen, without
745    /// mutating state.
746    #[must_use]
747    pub fn contains_trade(&self, trade_id: &TradeId) -> bool {
748        self.emitted_trades.lock().contains(trade_id)
749    }
750}
751
752#[derive(Debug)]
753struct OrderShape {
754    quantity: Quantity,
755    price: Option<Price>,
756    filled_qty: Decimal,
757    filled_qty_expected: Decimal,
758}
759
760#[derive(Debug, Clone, PartialEq, Eq)]
761pub(crate) struct OrderBinding {
762    pub identity: OrderIdentity,
763    pub venue_order_id: Option<VenueOrderId>,
764    pub venue_order_legs: Vec<VenueOrderId>,
765}
766
767#[cfg(test)]
768mod tests {
769    use nautilus_model::{
770        enums::{OrderSide, OrderType},
771        identifiers::{ClientOrderId, InstrumentId, StrategyId, TradeId, VenueOrderId},
772    };
773    use rstest::rstest;
774
775    use super::*;
776
777    fn sample_identity() -> OrderIdentity {
778        OrderIdentity {
779            instrument_id: InstrumentId::from("ETH-PERP.DERIVE"),
780            strategy_id: StrategyId::from("S-1"),
781            order_side: OrderSide::Buy,
782            order_type: OrderType::Limit,
783        }
784    }
785
786    #[rstest]
787    #[case(Decimal::ZERO, Decimal::ZERO)]
788    #[case(Decimal::new(4, 1), Decimal::ZERO)]
789    #[case(Decimal::new(4, 1), Decimal::new(4, 1))]
790    fn test_canceled_fill_target_includes_prior_legs(
791        #[case] prior_fills: Decimal,
792        #[case] delivered_prior_fills: Decimal,
793    ) {
794        let state = WsDispatchState::new(42);
795        let cid = ClientOrderId::from("CANCELED-REPLACEMENT");
796        let identity = sample_identity();
797        let quantity = Quantity::from_decimal_dp(Decimal::ONE + prior_fills, 3).unwrap();
798        let price = Some(Price::from("3501.00"));
799        state.register_identity(cid, identity);
800        state.record_order_shape(cid, quantity, price);
801        state.record_fill(
802            cid,
803            Quantity::from_decimal_dp(delivered_prior_fills, 3).unwrap(),
804        );
805        state.record_canceled(cid, Quantity::from("1.000"), Quantity::from("0.500"));
806
807        assert_eq!(state.identity(&cid), Some(identity));
808        assert_eq!(state.order_shape(&cid), Some((quantity, price)));
809        state.record_fill(cid, Quantity::from("0.200"));
810        state.record_canceled(cid, Quantity::from("1.000"), Quantity::from("0.500"));
811
812        assert_eq!(state.identity(&cid), Some(identity));
813        state.record_fill(cid, Quantity::from("0.300"));
814
815        let pending_prior_fills = prior_fills - delivered_prior_fills;
816        assert_eq!(
817            state.identity(&cid),
818            (!pending_prior_fills.is_zero()).then_some(identity),
819        );
820
821        if !pending_prior_fills.is_zero() {
822            state.record_fill(
823                cid,
824                Quantity::from_decimal_dp(pending_prior_fills, 3).unwrap(),
825            );
826        }
827
828        assert_eq!(state.identity(&cid), None);
829        assert_eq!(state.order_shape(&cid), None);
830    }
831
832    #[rstest]
833    #[case("0.000")]
834    #[case("0.500")]
835    fn test_canceled_without_pending_fills_retires_identity(#[case] filled_qty: &str) {
836        let state = WsDispatchState::new(42);
837        let cid = ClientOrderId::from("CANCELED-COMPLETE");
838        let filled_qty = Quantity::from(filled_qty);
839        state.register_identity(cid, sample_identity());
840        state.record_order_shape(cid, Quantity::from("1.000"), None);
841        state.record_fill(cid, filled_qty);
842        state.record_canceled(cid, Quantity::from("1.000"), filled_qty);
843
844        assert_eq!(state.identity(&cid), None);
845        assert_eq!(state.order_shape(&cid), None);
846    }
847
848    #[rstest]
849    fn test_instrument_precision_roundtrip() {
850        let state = WsDispatchState::new(42);
851        let instrument_id = InstrumentId::from("ETH-PERP.DERIVE");
852
853        assert_eq!(state.instrument_precision(&instrument_id), None);
854        state.register_instrument_precision(instrument_id, 2, 3);
855        assert_eq!(state.instrument_precision(&instrument_id), Some((2, 3)));
856    }
857
858    #[rstest]
859    fn test_register_and_identity_roundtrip() {
860        let state = WsDispatchState::new(42);
861        let cid = ClientOrderId::from("STRAT-O-1");
862        let identity = sample_identity();
863
864        assert!(state.identity(&cid).is_none());
865        state.register_identity(cid, identity);
866        assert_eq!(state.identity(&cid), Some(identity));
867
868        state.forget(&cid);
869        assert!(state.identity(&cid).is_none());
870    }
871
872    #[rstest]
873    fn test_mark_accepted_dedupes_second_call() {
874        let state = WsDispatchState::new(42);
875        let cid = ClientOrderId::from("STRAT-O-1");
876
877        assert!(!state.mark_accepted(cid));
878        assert!(state.contains_accepted(&cid));
879        assert!(state.mark_accepted(cid));
880    }
881
882    #[rstest]
883    fn test_active_acceptance_survives_replay_cache_eviction() {
884        let state = WsDispatchState::new(42);
885        let client_order_id = ClientOrderId::from("ACTIVE-0");
886        state.register_identity(client_order_id, sample_identity());
887        state.mark_accepted(client_order_id);
888
889        for n in 1..=ORDER_DEDUP_CAPACITY {
890            let other = ClientOrderId::new(format!("ACTIVE-{n}"));
891            state.register_identity(other, sample_identity());
892            state.mark_accepted(other);
893        }
894
895        assert_eq!(state.identity(&client_order_id), Some(sample_identity()));
896        assert!(state.contains_accepted(&client_order_id));
897        assert!(state.mark_accepted(client_order_id));
898    }
899
900    #[rstest]
901    fn test_check_and_insert_trade_returns_true_on_duplicate() {
902        let state = WsDispatchState::new(42);
903        let trade_id = TradeId::new("T-1");
904
905        assert!(!state.check_and_insert_trade(trade_id));
906        assert!(state.contains_trade(&trade_id));
907        assert!(state.check_and_insert_trade(trade_id));
908    }
909
910    #[rstest]
911    fn test_forget_clears_accepted_marker() {
912        let state = WsDispatchState::new(42);
913        let cid = ClientOrderId::from("STRAT-O-1");
914
915        state.mark_accepted(cid);
916        state.forget(&cid);
917        assert!(!state.contains_accepted(&cid));
918    }
919
920    #[rstest]
921    fn test_bound_venue_order_id_records_and_advances() {
922        let state = WsDispatchState::new(42);
923        let cid = ClientOrderId::from("STRAT-O-1");
924        let voi1 = VenueOrderId::from("voi-1");
925        let voi2 = VenueOrderId::from("voi-2");
926
927        assert!(state.bound_venue_order_id(&cid).is_none());
928        state.record_venue_order_id(cid, voi1);
929        assert_eq!(state.bound_venue_order_id(&cid), Some(voi1));
930        // A modify rebinds the order to the replacement venue order id.
931        state.record_venue_order_id(cid, voi2);
932        assert_eq!(state.bound_venue_order_id(&cid), Some(voi2));
933    }
934
935    #[rstest]
936    fn test_pending_modify_admission_does_not_replace_existing_operation() {
937        let state = WsDispatchState::new(42);
938        let cid = ClientOrderId::from("MODIFY-SERIAL");
939        let old_id = VenueOrderId::from("original-leg");
940        state.mark_pending_modify(cid, old_id);
941        state.record_modify_target(cid, Quantity::from("2.000"), Some(Price::from("3505.00")));
942        state.mark_pending_modify(cid, VenueOrderId::from("overlapping-leg"));
943        assert_eq!(state.pending_modify(&cid), Some(old_id));
944        assert_eq!(
945            state.modify_target(&cid),
946            Some((Quantity::from("2.000"), Some(Price::from("3505.00"))))
947        );
948    }
949
950    #[rstest]
951    fn test_pending_modify_marker_set_and_cleared() {
952        let state = WsDispatchState::new(42);
953        let cid = ClientOrderId::from("STRAT-O-1");
954        let old_voi = VenueOrderId::from("voi-1");
955
956        assert!(state.pending_modify(&cid).is_none());
957        state.mark_pending_modify(cid, old_voi);
958        assert_eq!(state.pending_modify(&cid), Some(old_voi));
959        state.clear_pending_modify(&cid);
960        assert!(state.pending_modify(&cid).is_none());
961    }
962
963    #[rstest]
964    fn test_bind_incoming_modify_advances_bound_venue_order_id() {
965        let state = WsDispatchState::new(42);
966        let cid = ClientOrderId::from("STRAT-O-1");
967        let old_voi = VenueOrderId::from("voi-old");
968        let new_voi = VenueOrderId::from("voi-new");
969        state.record_venue_order_id(cid, old_voi);
970        state.mark_pending_modify(cid, old_voi);
971
972        assert!(state.bind_incoming_modify(cid, new_voi, false));
973        assert_eq!(state.bound_venue_order_id(&cid), Some(new_voi));
974        assert!(!state.bind_incoming_modify(cid, VenueOrderId::from("voi-other"), true));
975        assert_eq!(state.bound_venue_order_id(&cid), Some(new_voi));
976        assert!(state.take_pending_modify(&cid, old_voi, None));
977        assert!(!state.take_pending_modify(&cid, old_voi, None));
978    }
979
980    #[rstest]
981    fn test_terminal_incoming_modify_claims_pending_response() {
982        let state = WsDispatchState::new(42);
983        let cid = ClientOrderId::from("STRAT-O-1");
984        let old_voi = VenueOrderId::from("voi-old");
985        state.record_venue_order_id(cid, old_voi);
986        state.mark_pending_modify(cid, old_voi);
987
988        assert!(state.bind_incoming_modify(cid, VenueOrderId::from("voi-rejected"), true));
989        assert!(state.pending_modify(&cid).is_none());
990        assert!(!state.take_pending_modify(&cid, old_voi, None));
991    }
992
993    #[rstest]
994    fn test_response_claim_rebinds_before_clearing_pending_modify() {
995        let state = WsDispatchState::new(42);
996        let cid = ClientOrderId::from("STRAT-O-1");
997        let old_voi = VenueOrderId::from("voi-old");
998        let new_voi = VenueOrderId::from("voi-new");
999        state.record_venue_order_id(cid, old_voi);
1000        state.mark_pending_modify(cid, old_voi);
1001
1002        assert!(state.take_pending_modify(&cid, old_voi, Some(new_voi)));
1003        assert_eq!(state.bound_venue_order_id(&cid), Some(new_voi));
1004        assert!(state.pending_modify(&cid).is_none());
1005    }
1006
1007    #[rstest]
1008    fn test_forget_clears_bound_and_pending() {
1009        let state = WsDispatchState::new(42);
1010        let cid = ClientOrderId::from("STRAT-O-1");
1011
1012        let identity = OrderIdentity {
1013            instrument_id: InstrumentId::from("ETH-PERP.DERIVE"),
1014            strategy_id: StrategyId::from("S-1"),
1015            order_side: OrderSide::Buy,
1016            order_type: OrderType::Limit,
1017        };
1018
1019        state.register_identity(cid, identity);
1020        state.record_venue_order_id(cid, VenueOrderId::from("voi-0"));
1021        state.record_venue_order_id(cid, VenueOrderId::from("voi-1"));
1022        state.mark_pending_modify(cid, VenueOrderId::from("voi-1"));
1023        state.forget(&cid);
1024        assert!(state.bound_venue_order_id(&cid).is_none());
1025        assert!(state.pending_modify(&cid).is_none());
1026        assert_eq!(state.identity(&cid), None);
1027        assert_eq!(state.known_instrument(&cid), Some(identity.instrument_id));
1028        assert!(state.is_terminal(&cid, identity.instrument_id));
1029        assert_eq!(
1030            state.order_binding(&cid),
1031            Some(OrderBinding {
1032                identity,
1033                venue_order_id: Some(VenueOrderId::from("voi-1")),
1034                venue_order_legs: vec![VenueOrderId::from("voi-0"), VenueOrderId::from("voi-1")]
1035            })
1036        );
1037    }
1038}