Skip to main content

nautilus_data/engine/
book.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
16use std::{cell::RefCell, num::NonZeroUsize, rc::Rc};
17
18use indexmap::IndexMap;
19use nautilus_common::{
20    cache::Cache,
21    messages::data::{SubscribeBookSnapshots, SubscribeCommand},
22    msgbus::{self, Handler, MStr, Topic, switchboard},
23    timer::TimeEvent,
24};
25use nautilus_core::UnixNanos;
26use nautilus_model::{
27    data::{OrderBookDeltas, OrderBookDepth, QuoteTick},
28    enums::{BookType, InstrumentClass},
29    identifiers::{ClientId, InstrumentId, Venue},
30    instruments::Instrument,
31    orderbook::OrderBook,
32};
33use ustr::Ustr;
34
35use super::{
36    BookDeltasResponse, BookDepthResponse, DataEngine, DurationNanos, FAILED, OrderBookDelta,
37    PARAMS_IS_PARENT, Params, RecordFlag, SubscribeBookDeltas, SubscribeBookDepth, SubscriptionKey,
38    TimeEventCallback, TypedHandler, UUID4, UnsubscribeBookDeltas, UnsubscribeBookDepth,
39    UnsubscribeBookSnapshots, UnsubscribeCommand, is_parent_subscription,
40    log_error_on_cache_insert,
41};
42
43impl DataEngine {
44    /// Returns all instrument IDs for which book delta subscriptions exist.
45    #[must_use]
46    pub fn subscribed_book_deltas(&self) -> Vec<InstrumentId> {
47        self.collect_subscriptions(|client| &client.subscriptions_book_deltas)
48    }
49
50    /// Returns all instrument IDs for which book depth subscriptions exist.
51    #[must_use]
52    pub fn subscribed_book_depth(&self) -> Vec<InstrumentId> {
53        self.collect_subscriptions(|client| &client.subscriptions_book_depth)
54    }
55
56    /// Returns all instrument IDs for which book snapshot subscriptions exist.
57    #[must_use]
58    pub fn subscribed_book_snapshots(&self) -> Vec<InstrumentId> {
59        self.book_snapshot_counts
60            .keys()
61            .map(|(instrument_id, _)| *instrument_id)
62            .collect()
63    }
64
65    /// Returns whether a retained book subscription names or covers `instrument_id`.
66    ///
67    /// Includes resolved parent targets and ownership retained after a client subscription failure.
68    /// Does not indicate that an upstream feed is active or a book is complete.
69    #[must_use]
70    pub fn has_book_subscription(&self, instrument_id: &InstrumentId) -> bool {
71        self.book_subscription_owners.contains_key(instrument_id)
72            || self.book_subscriptions.contains_key(instrument_id)
73            || self.subscriptions_external.iter().any(|((_, key), _)| {
74                matches!(
75                    key,
76                    SubscriptionKey::BookDeltas(id)
77                        | SubscriptionKey::BookDepth(id)
78                        | SubscriptionKey::BookSnapshots(id, _)
79                        if id == instrument_id
80                )
81            })
82    }
83
84    pub(super) fn subscribe_book_deltas(
85        &mut self,
86        cmd: &SubscribeBookDeltas,
87    ) -> anyhow::Result<bool> {
88        let instrument_id = cmd.single_instrument_id()?;
89        if instrument_id.is_synthetic()
90            && !cmd.client_id.is_some_and(|id| self.is_external_client(id))
91        {
92            anyhow::bail!("Cannot subscribe for synthetic instrument `OrderBookDelta` data");
93        }
94
95        let had_deltas =
96            self.has_book_delta_subscription_key(instrument_id, cmd.client_id, cmd.venue);
97
98        self.retain_book_subscription(SubscribeCommand::BookDeltas(cmd.clone()))?;
99
100        self.increment_book_delta_subscription(instrument_id, cmd.client_id, cmd.venue);
101
102        Ok(!had_deltas)
103    }
104
105    pub(super) fn subscribe_book_depth(
106        &mut self,
107        cmd: &SubscribeBookDepth,
108    ) -> anyhow::Result<bool> {
109        let instrument_id = cmd.single_instrument_id()?;
110        if instrument_id.is_synthetic()
111            && !cmd.client_id.is_some_and(|id| self.is_external_client(id))
112        {
113            anyhow::bail!("Cannot subscribe for synthetic instrument `OrderBookDepth` data");
114        }
115
116        let had_depth =
117            self.has_book_depth_subscription_key(instrument_id, cmd.client_id, cmd.venue);
118
119        self.retain_book_subscription(SubscribeCommand::BookDepth(cmd.clone()))?;
120
121        self.increment_book_depth_subscription(instrument_id, cmd.client_id, cmd.venue);
122
123        Ok(!had_depth)
124    }
125
126    pub(super) fn subscribe_book_snapshots(
127        &mut self,
128        cmd: &SubscribeBookSnapshots,
129    ) -> anyhow::Result<()> {
130        let instrument_id = cmd.single_instrument_id()?;
131        if instrument_id.is_synthetic() {
132            anyhow::bail!("Cannot subscribe for synthetic instrument `OrderBookDelta` data");
133        }
134
135        let parent = resolve_parent_components(&instrument_id, cmd.params.as_ref())?;
136
137        let had_snapshots = self.has_book_snapshot_subscriptions(&instrument_id);
138
139        self.retain_book_subscription(SubscribeCommand::BookSnapshots(cmd.clone()))?;
140
141        self.increment_book_snapshot_subscription(cmd, parent);
142
143        if !had_snapshots {
144            self.book_snapshot_sources.insert(
145                instrument_id,
146                BookSnapshotSource {
147                    command: cmd.clone(),
148                    client_command: SubscribeCommand::BookDeltas(SubscribeBookDeltas::new(
149                        instrument_id,
150                        cmd.book_type,
151                        cmd.client_id,
152                        cmd.venue,
153                        UUID4::new(),
154                        cmd.ts_init,
155                        cmd.depth,
156                        true, // managed
157                        Some(cmd.command_id),
158                        cmd.params.clone(),
159                    )),
160                },
161            );
162        }
163
164        let source = self
165            .book_snapshot_sources
166            .get(&instrument_id)
167            .cloned()
168            .expect("snapshot source command must exist after increment");
169        self.subscribe_book_snapshot_source(&source.command, source.client_command);
170
171        Ok(())
172    }
173
174    fn subscribe_book_snapshot_source(
175        &mut self,
176        cmd: &SubscribeBookSnapshots,
177        client_command: SubscribeCommand,
178    ) {
179        let instrument_id = cmd
180            .single_instrument_id()
181            .expect("instrument command has one member at this boundary");
182
183        if let Some(client_id) = cmd.client_id.as_ref()
184            && self.is_external_client(*client_id)
185        {
186            if self.config.debug {
187                log::debug!("Skipping subscribe command for external client {client_id}: {cmd:?}");
188            }
189
190            return;
191        }
192
193        log::debug!(
194            "Forwarding BookSnapshots as BookDeltas for {}, client_id={:?}, venue={:?}",
195            instrument_id,
196            cmd.client_id,
197            cmd.venue,
198        );
199
200        if let Some(client) = self.get_command_client(cmd.client_id.as_ref(), cmd.venue.as_ref()) {
201            log::debug!("Calling client.execute_subscribe for BookDeltas: {instrument_id}");
202            client.execute_subscribe(client_command);
203        } else {
204            log::error!(
205                "Cannot handle command: no client found for client_id={:?}, venue={:?}",
206                cmd.client_id,
207                cmd.venue,
208            );
209        }
210    }
211
212    pub(super) fn unsubscribe_book_deltas(&mut self, cmd: &UnsubscribeBookDeltas) -> bool {
213        let instrument_id = cmd
214            .single_instrument_id()
215            .expect("instrument command has one member at this boundary");
216
217        match self.decrement_book_delta_subscription(instrument_id, cmd.client_id, cmd.venue) {
218            BookDeltasUnsubscribeResult::NotSubscribed => {
219                log::warn!("Cannot unsubscribe from `OrderBookDeltas` data: not subscribed");
220                return false;
221            }
222            BookDeltasUnsubscribeResult::Decremented => return false,
223            BookDeltasUnsubscribeResult::Removed => {}
224        }
225
226        true
227    }
228
229    pub(super) fn unsubscribe_book_depth(&mut self, cmd: &UnsubscribeBookDepth) -> bool {
230        let instrument_id = cmd
231            .single_instrument_id()
232            .expect("instrument command has one member at this boundary");
233
234        match self.decrement_book_depth_subscription(instrument_id, cmd.client_id, cmd.venue) {
235            BookDeltasUnsubscribeResult::NotSubscribed => {
236                log::warn!("Cannot unsubscribe from `OrderBookDepth` data: not subscribed");
237                return false;
238            }
239            BookDeltasUnsubscribeResult::Decremented => return false,
240            BookDeltasUnsubscribeResult::Removed => {}
241        }
242
243        true
244    }
245
246    pub(super) fn unsubscribe_book_snapshots(&mut self, cmd: &UnsubscribeBookSnapshots) {
247        let instrument_id = cmd
248            .single_instrument_id()
249            .expect("instrument command has one member at this boundary");
250
251        match self.decrement_book_snapshot_subscription(instrument_id, cmd.interval_ms) {
252            BookSnapshotUnsubscribeResult::NotSubscribed => {
253                log::warn!("Cannot unsubscribe from `OrderBook` snapshots: not subscribed");
254                return;
255            }
256            BookSnapshotUnsubscribeResult::Decremented => return,
257            BookSnapshotUnsubscribeResult::Removed => {}
258        }
259
260        if self.has_book_snapshot_subscriptions(&instrument_id) {
261            return;
262        }
263
264        let Some(source) = self.book_snapshot_sources.remove(&instrument_id) else {
265            log::error!(
266                "Cannot release order book snapshot source for {instrument_id}: command not retained",
267            );
268            return;
269        };
270
271        if let Some(client_id) = source.command.client_id.as_ref()
272            && self.is_external_client(*client_id)
273        {
274            return;
275        }
276
277        if let Some(client) = self.get_command_client(
278            source.command.client_id.as_ref(),
279            source.command.venue.as_ref(),
280        ) {
281            let deltas_cmd = UnsubscribeBookDeltas::new(
282                source
283                    .command
284                    .single_instrument_id()
285                    .expect("book commands are projected onto one instrument"),
286                source.command.client_id,
287                source.command.venue,
288                UUID4::new(),
289                cmd.ts_init,
290                Some(source.command.command_id),
291                source.command.params,
292            );
293            client.execute_unsubscribe(&UnsubscribeCommand::BookDeltas(deltas_cmd));
294        }
295    }
296
297    fn retain_book_subscription(&mut self, command: SubscribeCommand) -> anyhow::Result<()> {
298        let instrument_id = match &command {
299            SubscribeCommand::BookDeltas(cmd) => cmd
300                .single_instrument_id()
301                .expect("book commands are projected onto one instrument"),
302            SubscribeCommand::BookDepth(cmd) => cmd
303                .single_instrument_id()
304                .expect("book commands are projected onto one instrument"),
305            SubscribeCommand::BookSnapshots(cmd) => cmd
306                .single_instrument_id()
307                .expect("book commands are projected onto one instrument"),
308            _ => unreachable!("only book subscriptions are retained"),
309        };
310
311        let parent = resolve_parent_components(&instrument_id, command.params())?;
312
313        let targets = if let Some((root, class)) = parent {
314            self.cache
315                .borrow()
316                .instruments_by_parent(&instrument_id.venue, &root, class)
317                .iter()
318                .map(|instrument| instrument.id())
319                .collect()
320        } else {
321            vec![instrument_id]
322        };
323
324        let client_id = if let Some(client_id) = command.client_id()
325            && self.is_external_client(*client_id)
326        {
327            Some(*client_id)
328        } else {
329            self.get_command_client(command.client_id(), command.venue())
330                .map(|client| client.client_id)
331        };
332
333        let subscription = Rc::new(BookSubscriptionOwner {
334            command,
335            client_id,
336            targets,
337        });
338
339        let mut params = subscription
340            .command
341            .params()
342            .map_or_default(|params| IndexMap::clone(params));
343        params.shift_remove(PARAMS_IS_PARENT);
344
345        for active in subscription
346            .targets
347            .iter()
348            .filter_map(|id| self.book_subscriptions.get(id))
349            .flat_map(|book| &book.owners)
350        {
351            if !subscription.managed()
352                && !active.managed()
353                && subscription.client_id != active.client_id
354            {
355                continue;
356            }
357
358            if subscription.is_depth() != active.is_depth() {
359                anyhow::ensure!(
360                    !subscription.managed() || !active.managed(),
361                    "Conflicting managed book source for {instrument_id}: deltas and depth cannot both manage the same book; use managed=false for the other subscription"
362                );
363                continue;
364            }
365
366            let mut active_params = active
367                .command
368                .params()
369                .map_or_default(|params| IndexMap::clone(params));
370            active_params.shift_remove(PARAMS_IS_PARENT);
371            anyhow::ensure!(
372                subscription.client_id == active.client_id
373                    && subscription.config() == active.config()
374                    && params == active_params,
375                "Conflicting book subscription for {instrument_id}: shared book sources must use the same client, book type, depth, and parameters"
376            );
377        }
378
379        if subscription.managed() {
380            self.setup_book_updater(
381                &subscription.targets,
382                subscription.config().0,
383                subscription.is_depth(),
384            )?;
385        }
386
387        for target_id in &subscription.targets {
388            self.book_subscriptions
389                .entry(*target_id)
390                .or_default()
391                .owners
392                .push(Rc::clone(&subscription));
393        }
394
395        self.book_subscription_owners
396            .entry(instrument_id)
397            .or_default()
398            .push(subscription);
399        Ok(())
400    }
401
402    pub(super) fn clear_book_state(&mut self) {
403        let book_updaters: Vec<_> = self.book_updaters.drain().collect();
404        for (instrument_id, updater) in book_updaters {
405            Self::unsubscribe_book_updater(instrument_id, updater);
406        }
407
408        self.book_subscriptions.clear();
409        self.book_subscription_owners.clear();
410
411        self.book_deltas_counts.clear();
412        self.book_depth_counts.clear();
413        self.book_intervals.clear();
414        self.book_snapshot_counts.clear();
415        self.book_snapshot_sources.clear();
416        self.book_snapshotters.clear();
417        self.buffered_deltas_map.clear();
418        self.deltas_frame.clear();
419    }
420
421    pub(super) fn release_book_subscription(&mut self, command: &UnsubscribeCommand) -> bool {
422        let key = SubscriptionKey::from_unsubscribe(command);
423
424        let instrument_id = match command {
425            UnsubscribeCommand::BookDeltas(cmd) => cmd
426                .single_instrument_id()
427                .expect("book commands are projected onto one instrument"),
428            UnsubscribeCommand::BookDepth(cmd) => cmd
429                .single_instrument_id()
430                .expect("book commands are projected onto one instrument"),
431            UnsubscribeCommand::BookSnapshots(cmd) => cmd
432                .single_instrument_id()
433                .expect("book commands are projected onto one instrument"),
434            _ => unreachable!("only book subscriptions are released"),
435        };
436
437        let Some(owners) = self.book_subscription_owners.get_mut(&instrument_id) else {
438            return false;
439        };
440
441        let index = owners.iter().position(|subscription| {
442            SubscriptionKey::from_subscribe(&subscription.command) == key
443                && subscription.command.client_id() == command.client_id()
444                && subscription.command.venue() == command.venue()
445                && command
446                    .correlation_id()
447                    .is_none_or(|id| subscription.command.command_id() == id)
448        });
449
450        let Some(index) = index else {
451            return false;
452        };
453
454        let subscription = owners.remove(index);
455        if owners.is_empty() {
456            self.book_subscription_owners.remove(&instrument_id);
457        }
458
459        for &target_id in &subscription.targets {
460            let book = self
461                .book_subscriptions
462                .get_mut(&target_id)
463                .expect("retained book subscription");
464            book.owners
465                .retain(|owner| !Rc::ptr_eq(owner, &subscription));
466            let managed = book.owners.iter().any(|owner| owner.managed());
467            if book.owners.is_empty() {
468                self.book_subscriptions.remove(&target_id);
469            }
470
471            if managed {
472                continue;
473            }
474
475            let Some(updater) = self.book_updaters.remove(&target_id) else {
476                continue;
477            };
478
479            Self::unsubscribe_book_updater(target_id, updater);
480        }
481
482        true
483    }
484
485    fn unsubscribe_book_updater(instrument_id: InstrumentId, updater: Rc<BookUpdater>) {
486        // Updaters use per-underlying topics; release router ownership before dropping them
487        let deltas_handler: TypedHandler<OrderBookDeltas> = TypedHandler::new(Rc::clone(&updater));
488        let depth_handler: TypedHandler<OrderBookDepth> = TypedHandler::new(updater);
489        msgbus::unsubscribe_book_deltas(
490            switchboard::get_book_deltas_topic(instrument_id).into(),
491            &deltas_handler,
492        );
493        msgbus::unsubscribe_book_depth(
494            switchboard::get_book_depth_topic(instrument_id).into(),
495            &depth_handler,
496        );
497    }
498
499    fn has_book_snapshot_subscriptions(&self, instrument_id: &InstrumentId) -> bool {
500        self.book_snapshot_counts
501            .keys()
502            .any(|(id, _)| id == instrument_id)
503    }
504
505    fn has_book_delta_subscription_key(
506        &self,
507        instrument_id: InstrumentId,
508        client_id: Option<ClientId>,
509        venue: Option<Venue>,
510    ) -> bool {
511        self.book_deltas_counts
512            .contains_key(&(instrument_id, client_id, venue))
513    }
514
515    fn has_book_depth_subscription_key(
516        &self,
517        instrument_id: InstrumentId,
518        client_id: Option<ClientId>,
519        venue: Option<Venue>,
520    ) -> bool {
521        self.book_depth_counts
522            .contains_key(&(instrument_id, client_id, venue))
523    }
524
525    fn increment_book_delta_subscription(
526        &mut self,
527        instrument_id: InstrumentId,
528        client_id: Option<ClientId>,
529        venue: Option<Venue>,
530    ) {
531        let key = (instrument_id, client_id, venue);
532
533        if let Some(count) = self.book_deltas_counts.get_mut(&key) {
534            *count += 1;
535        } else {
536            self.book_deltas_counts.insert(key, 1);
537        }
538    }
539
540    fn decrement_book_delta_subscription(
541        &mut self,
542        instrument_id: InstrumentId,
543        client_id: Option<ClientId>,
544        venue: Option<Venue>,
545    ) -> BookDeltasUnsubscribeResult {
546        let key = (instrument_id, client_id, venue);
547
548        let Some(count) = self.book_deltas_counts.get_mut(&key) else {
549            return BookDeltasUnsubscribeResult::NotSubscribed;
550        };
551
552        if *count > 1 {
553            *count -= 1;
554            return BookDeltasUnsubscribeResult::Decremented;
555        }
556
557        self.book_deltas_counts.shift_remove(&key);
558        BookDeltasUnsubscribeResult::Removed
559    }
560
561    fn increment_book_depth_subscription(
562        &mut self,
563        instrument_id: InstrumentId,
564        client_id: Option<ClientId>,
565        venue: Option<Venue>,
566    ) {
567        let key = (instrument_id, client_id, venue);
568        *self.book_depth_counts.entry(key).or_insert(0) += 1;
569    }
570
571    fn decrement_book_depth_subscription(
572        &mut self,
573        instrument_id: InstrumentId,
574        client_id: Option<ClientId>,
575        venue: Option<Venue>,
576    ) -> BookDeltasUnsubscribeResult {
577        let key = (instrument_id, client_id, venue);
578
579        let Some(count) = self.book_depth_counts.get_mut(&key) else {
580            return BookDeltasUnsubscribeResult::NotSubscribed;
581        };
582
583        if *count > 1 {
584            *count -= 1;
585            return BookDeltasUnsubscribeResult::Decremented;
586        }
587
588        self.book_depth_counts.shift_remove(&key);
589        BookDeltasUnsubscribeResult::Removed
590    }
591
592    fn increment_book_snapshot_subscription(
593        &mut self,
594        cmd: &SubscribeBookSnapshots,
595        parent: Option<(Ustr, InstrumentClass)>,
596    ) -> bool {
597        let instrument_id = cmd
598            .single_instrument_id()
599            .expect("instrument command has one member at this boundary");
600        let key = (instrument_id, cmd.interval_ms);
601
602        if let Some(count) = self.book_snapshot_counts.get_mut(&key) {
603            *count += 1;
604            return false;
605        }
606
607        self.book_snapshot_counts.insert(key, 1);
608
609        let snapshot_infos = if let Some(snapshot_infos) = self.book_intervals.get(&cmd.interval_ms)
610        {
611            Rc::clone(snapshot_infos)
612        } else {
613            let snapshot_infos = Rc::new(RefCell::new(IndexMap::new()));
614            self.book_intervals
615                .insert(cmd.interval_ms, Rc::clone(&snapshot_infos));
616            self.schedule_book_snapshotter(cmd.interval_ms, Rc::clone(&snapshot_infos));
617            snapshot_infos
618        };
619
620        let topic = switchboard::get_book_snapshots_topic(instrument_id, cmd.interval_ms);
621
622        let snap_info = BookSnapshotInfo {
623            instrument_id,
624            venue: instrument_id.venue,
625            parent,
626            topic,
627            interval_ms: cmd.interval_ms,
628        };
629
630        snapshot_infos.borrow_mut().insert(instrument_id, snap_info);
631
632        true
633    }
634
635    fn decrement_book_snapshot_subscription(
636        &mut self,
637        instrument_id: InstrumentId,
638        interval_ms: NonZeroUsize,
639    ) -> BookSnapshotUnsubscribeResult {
640        let key = (instrument_id, interval_ms);
641
642        let Some(count) = self.book_snapshot_counts.get_mut(&key) else {
643            return BookSnapshotUnsubscribeResult::NotSubscribed;
644        };
645
646        if *count > 1 {
647            *count -= 1;
648            return BookSnapshotUnsubscribeResult::Decremented;
649        }
650
651        self.book_snapshot_counts.shift_remove(&key);
652
653        let remove_interval = if let Some(snapshot_infos) = self.book_intervals.get(&interval_ms) {
654            let mut snapshot_infos = snapshot_infos.borrow_mut();
655            snapshot_infos.shift_remove(&instrument_id);
656            snapshot_infos.is_empty()
657        } else {
658            false
659        };
660
661        if remove_interval {
662            self.book_intervals.remove(&interval_ms);
663
664            if let Some(snapshotter) = self.book_snapshotters.remove(&interval_ms) {
665                let timer_name = snapshotter.timer_name;
666                let mut clock = self.clock.borrow_mut();
667                if clock.timer_exists(&timer_name) {
668                    clock.cancel_timer(&timer_name);
669                }
670            }
671        }
672
673        BookSnapshotUnsubscribeResult::Removed
674    }
675
676    fn schedule_book_snapshotter(
677        &mut self,
678        interval_ms: NonZeroUsize,
679        snapshot_infos: BookSnapshotInfos,
680    ) {
681        let interval_ms_u64 =
682            u64::try_from(interval_ms.get()).expect("Snapshot interval exceeds u64");
683        let interval_ns = DurationNanos::from_millis(interval_ms_u64);
684        let now_ns = self.clock.borrow().timestamp_ns();
685        let start_time_ns = now_ns
686            .floor(interval_ns)
687            .checked_add(interval_ns)
688            .expect("Book snapshot timer start exceeds UnixNanos range");
689
690        let snapshotter = Rc::new(BookSnapshotter::new(
691            interval_ms,
692            snapshot_infos,
693            Rc::clone(&self.cache),
694        ));
695        let timer_name = snapshotter.timer_name;
696        let snapshotter_callback = Rc::clone(&snapshotter);
697        let callback_fn: Rc<dyn Fn(TimeEvent)> =
698            Rc::new(move |event| snapshotter_callback.snapshot(event));
699        let callback = TimeEventCallback::from(callback_fn);
700
701        self.clock
702            .borrow_mut()
703            .set_timer_ns(
704                &timer_name,
705                interval_ns,
706                Some(start_time_ns),
707                None,
708                Some(callback),
709                None,
710                None,
711            )
712            .expect(FAILED);
713
714        self.book_snapshotters.insert(interval_ms, snapshotter);
715    }
716
717    // Skip cache writes that would regress a book a `BookUpdater` is maintaining.
718    // Unmanaged subscriptions don't install a `BookUpdater`, so they don't gate writes.
719    fn cache_is_owned_by_live_subscription(&self, instrument_id: &InstrumentId) -> bool {
720        self.book_updaters.contains_key(instrument_id)
721    }
722
723    pub(super) fn handle_book_response(&self, book: &OrderBook) {
724        if self.cache_is_owned_by_live_subscription(&book.instrument_id) {
725            log::debug!(
726                "Skipping cache write for order book {}: live subscription owns the book",
727                book.instrument_id,
728            );
729            return;
730        }
731
732        log::debug!("Adding order book {} to cache", book.instrument_id);
733
734        if let Err(e) = self
735            .cache
736            .as_ref()
737            .borrow_mut()
738            .add_order_book(book.clone())
739        {
740            log_error_on_cache_insert(&e);
741        }
742    }
743
744    pub(super) fn handle_book_deltas_response(&self, resp: &BookDeltasResponse) {
745        if !self.cache_is_owned_by_live_subscription(&resp.instrument_id) {
746            let mut cache = self.cache.as_ref().borrow_mut();
747            if let Some(book) = cache.order_book_mut(&resp.instrument_id) {
748                for delta in resp.data.iter() {
749                    if let Err(e) = book.apply_delta(delta) {
750                        log::error!("Failed to apply historical delta to cache: {e}");
751                    }
752                }
753            } else {
754                log::debug!(
755                    "Skipping cache write for {} historical deltas on {}: no cache book yet",
756                    resp.data.len(),
757                    resp.instrument_id,
758                );
759            }
760        }
761
762        // Group deltas by `F_LAST` so each published batch preserves the original event
763        // boundary and metadata (timestamps and sequence from the closing delta), matching
764        // the live `handle_delta` buffering semantic. Collapsing the whole response into
765        // one batch would surface a synthetic event with the trailing delta's flags only.
766        if resp.data.is_empty() {
767            return;
768        }
769
770        let topic = switchboard::get_pipeline_book_deltas_topic(resp.instrument_id);
771        let mut frame: Vec<OrderBookDelta> = Vec::new();
772        for delta in resp.data.iter() {
773            frame.push(*delta);
774            if RecordFlag::F_LAST.matches(delta.flags) {
775                let batch = OrderBookDeltas::new(resp.instrument_id, std::mem::take(&mut frame));
776                msgbus::publish_deltas(topic, &batch);
777            }
778        }
779
780        if !frame.is_empty() {
781            let batch = OrderBookDeltas::new(resp.instrument_id, frame);
782            msgbus::publish_deltas(topic, &batch);
783        }
784    }
785
786    pub(super) fn handle_book_depth_response(&self, resp: &BookDepthResponse) {
787        let topic = switchboard::get_pipeline_book_depth_topic(resp.instrument_id);
788        for depth in resp.data.iter() {
789            msgbus::publish_depth(topic, depth);
790        }
791    }
792
793    fn setup_book_updater(
794        &mut self,
795        target_ids: &[InstrumentId],
796        book_type: BookType,
797        depth: bool,
798    ) -> anyhow::Result<()> {
799        {
800            let mut cache = self.cache.borrow_mut();
801            for target_id in target_ids {
802                if cache
803                    .order_book(target_id)
804                    .is_none_or(|book| book.book_type != book_type)
805                {
806                    cache.add_order_book(OrderBook::new(*target_id, book_type))?;
807                }
808            }
809        }
810
811        for target_id in target_ids {
812            let updater = Rc::clone(self.book_updaters.entry(*target_id).or_insert_with(|| {
813                Rc::new(BookUpdater::new(
814                    target_id,
815                    Rc::clone(&self.cache),
816                    self.config.emit_quotes_from_book,
817                ))
818            }));
819
820            if depth {
821                msgbus::subscribe_book_depth(
822                    switchboard::get_book_depth_topic(*target_id).into(),
823                    TypedHandler::new(updater),
824                    Some(self.msgbus_priority),
825                );
826            } else {
827                msgbus::subscribe_book_deltas(
828                    switchboard::get_book_deltas_topic(*target_id).into(),
829                    TypedHandler::new(updater),
830                    Some(self.msgbus_priority),
831                );
832            }
833        }
834
835        Ok(())
836    }
837}
838
839#[derive(Debug, Default)]
840pub(super) struct BookSubscription {
841    pub(super) owners: Vec<Rc<BookSubscriptionOwner>>,
842}
843
844#[derive(Debug)]
845pub(super) struct BookSubscriptionOwner {
846    pub(super) command: SubscribeCommand,
847    pub(super) client_id: Option<ClientId>,
848    pub(super) targets: Vec<InstrumentId>,
849}
850
851impl BookSubscriptionOwner {
852    pub(super) fn managed(&self) -> bool {
853        match &self.command {
854            SubscribeCommand::BookDeltas(cmd) => cmd.managed,
855            SubscribeCommand::BookDepth(cmd) => cmd.managed,
856            SubscribeCommand::BookSnapshots(_) => true,
857            _ => unreachable!("only book subscriptions are retained"),
858        }
859    }
860
861    pub(super) fn is_depth(&self) -> bool {
862        matches!(self.command, SubscribeCommand::BookDepth(_))
863    }
864
865    pub(super) fn config(&self) -> (BookType, Option<NonZeroUsize>) {
866        match &self.command {
867            SubscribeCommand::BookDeltas(cmd) => (cmd.book_type, cmd.depth),
868            SubscribeCommand::BookDepth(cmd) => (cmd.book_type, cmd.depth),
869            SubscribeCommand::BookSnapshots(cmd) => (cmd.book_type, cmd.depth),
870            _ => unreachable!("only book subscriptions are retained"),
871        }
872    }
873}
874
875#[derive(Clone, Debug)]
876pub(super) struct BookSnapshotSource {
877    pub(super) command: SubscribeBookSnapshots,
878    pub(super) client_command: SubscribeCommand,
879}
880
881/// Contains information for creating snapshots of specific order books.
882#[derive(Clone, Debug)]
883pub struct BookSnapshotInfo {
884    pub instrument_id: InstrumentId,
885    pub venue: Venue,
886    /// Parent expansion components `(root, class)` when this snapshot subscription
887    /// targets a parent symbol. `None` for concrete (exact-instrument) subscriptions.
888    pub parent: Option<(Ustr, InstrumentClass)>,
889    pub topic: MStr<Topic>,
890    pub interval_ms: NonZeroUsize,
891}
892
893/// Reference-counted map of per-instrument book snapshot descriptors.
894///
895/// Shared between the engine (which populates it on subscribe) and the
896/// [`BookSnapshotter`] timer callback (which iterates it on each tick).
897pub(crate) type BookSnapshotInfos = Rc<RefCell<IndexMap<InstrumentId, BookSnapshotInfo>>>;
898
899/// Reference count key for a book snapshot subscription.
900pub(crate) type BookSnapshotKey = (InstrumentId, NonZeroUsize);
901
902/// Outcome of decrementing a book snapshot subscription.
903pub(crate) enum BookSnapshotUnsubscribeResult {
904    /// No matching subscription was found.
905    NotSubscribed,
906    /// The reference count was decremented but other consumers remain.
907    Decremented,
908    /// The last consumer was removed; tear down associated state.
909    Removed,
910}
911
912/// Reference count key for a book deltas subscription.
913pub(crate) type BookDeltasKey = (InstrumentId, Option<ClientId>, Option<Venue>);
914
915/// Outcome of decrementing a book deltas subscription.
916pub(crate) enum BookDeltasUnsubscribeResult {
917    /// No matching subscription was found.
918    NotSubscribed,
919    /// The reference count was decremented but other consumers remain.
920    Decremented,
921    /// The last consumer was removed; tear down associated state.
922    Removed,
923}
924
925/// Handles order book updates and delta processing for a specific instrument.
926///
927/// The `BookUpdater` processes incoming order book deltas and maintains
928/// the current state of an order book. It can handle both incremental
929/// updates and full snapshots for the instrument it's assigned to.
930/// When `emit_quotes_from_book` is enabled, derived quotes use the book's last
931/// event time for `ts_event` and the incoming update's `ts_init`.
932#[derive(Debug)]
933pub struct BookUpdater {
934    pub id: Ustr,
935    pub instrument_id: InstrumentId,
936    pub cache: Rc<RefCell<Cache>>,
937    pub emit_quotes_from_book: bool,
938}
939
940impl BookUpdater {
941    /// Creates a new [`BookUpdater`] instance.
942    pub fn new(
943        instrument_id: &InstrumentId,
944        cache: Rc<RefCell<Cache>>,
945        emit_quotes_from_book: bool,
946    ) -> Self {
947        Self {
948            id: Ustr::from(&format!("{}-{}", stringify!(BookUpdater), instrument_id)),
949            instrument_id: *instrument_id,
950            cache,
951            emit_quotes_from_book,
952        }
953    }
954}
955
956impl Handler<OrderBookDeltas> for BookUpdater {
957    fn id(&self) -> Ustr {
958        self.id
959    }
960
961    fn handle(&self, deltas: &OrderBookDeltas) {
962        let mut emit: Option<QuoteTick> = None;
963        {
964            let mut cache = self.cache.borrow_mut();
965            if let Some(book) = cache.order_book_mut(&deltas.instrument_id) {
966                if let Err(e) = book.apply_deltas(deltas) {
967                    log::error!("Failed to apply deltas: {e}");
968                    return;
969                }
970
971                if self.emit_quotes_from_book {
972                    emit = derive_quote_from_book(book, deltas.ts_init);
973                }
974            }
975        }
976
977        if let Some(quote) = emit {
978            publish_quote_if_changed(&self.cache, quote);
979        }
980    }
981}
982
983impl Handler<OrderBookDepth> for BookUpdater {
984    fn id(&self) -> Ustr {
985        self.id
986    }
987
988    fn handle(&self, depth: &OrderBookDepth) {
989        let mut emit: Option<QuoteTick> = None;
990        {
991            let mut cache = self.cache.borrow_mut();
992            if let Some(book) = cache.order_book_mut(&depth.instrument_id) {
993                if let Err(e) = book.apply_depth(depth) {
994                    log::error!("Failed to apply depth: {e}");
995                    return;
996                }
997
998                if self.emit_quotes_from_book {
999                    emit = derive_quote_from_book(book, depth.ts_init);
1000                }
1001            }
1002        }
1003
1004        if let Some(quote) = emit {
1005            publish_quote_if_changed(&self.cache, quote);
1006        }
1007    }
1008}
1009
1010fn derive_quote_from_book(book: &OrderBook, ts_init: UnixNanos) -> Option<QuoteTick> {
1011    let bid_price = book.best_bid_price()?;
1012    let ask_price = book.best_ask_price()?;
1013    let bid_size = book.best_bid_size()?;
1014    let ask_size = book.best_ask_size()?;
1015
1016    if bid_size.is_zero() || ask_size.is_zero() {
1017        return None;
1018    }
1019
1020    Some(QuoteTick::new(
1021        book.instrument_id,
1022        bid_price,
1023        ask_price,
1024        bid_size,
1025        ask_size,
1026        book.ts_last,
1027        ts_init,
1028    ))
1029}
1030
1031/// Publishes the derived `QuoteTick` if top-of-book changed.
1032///
1033/// Writes to cache and republishes only when bid/ask price or size differs
1034/// from the cached quote.
1035pub(crate) fn publish_quote_if_changed(cache: &Rc<RefCell<Cache>>, quote: QuoteTick) {
1036    let publish = {
1037        let cache_ref = cache.borrow();
1038        match cache_ref.quote(&quote.instrument_id) {
1039            None => true,
1040            Some(last) => {
1041                last.bid_price != quote.bid_price
1042                    || last.ask_price != quote.ask_price
1043                    || last.bid_size != quote.bid_size
1044                    || last.ask_size != quote.ask_size
1045            }
1046        }
1047    };
1048
1049    if !publish {
1050        return;
1051    }
1052
1053    if let Err(e) = cache.borrow_mut().add_quote(quote) {
1054        log::error!("Error on cache insert: {e}");
1055    }
1056
1057    let topic = switchboard::get_quotes_topic(quote.instrument_id);
1058    msgbus::publish_quote(topic, &quote);
1059}
1060
1061/// Creates periodic snapshots of order books at configured intervals.
1062///
1063/// The `BookSnapshotter` generates order book snapshots on timer events,
1064/// publishing them as market data. This is useful for providing periodic
1065/// full order book state updates in addition to incremental delta updates.
1066#[derive(Debug)]
1067pub struct BookSnapshotter {
1068    pub timer_name: Ustr,
1069    pub interval_ms: NonZeroUsize,
1070    pub snapshot_infos: Rc<RefCell<IndexMap<InstrumentId, BookSnapshotInfo>>>,
1071    pub cache: Rc<RefCell<Cache>>,
1072}
1073
1074impl BookSnapshotter {
1075    /// Creates a new [`BookSnapshotter`] instance.
1076    pub fn new(
1077        interval_ms: NonZeroUsize,
1078        snapshot_infos: Rc<RefCell<IndexMap<InstrumentId, BookSnapshotInfo>>>,
1079        cache: Rc<RefCell<Cache>>,
1080    ) -> Self {
1081        let timer_name = format!("OrderBookSnapshots|{interval_ms}");
1082
1083        Self {
1084            timer_name: Ustr::from(&timer_name),
1085            interval_ms,
1086            snapshot_infos,
1087            cache,
1088        }
1089    }
1090
1091    /// Publishes a snapshot for each subscribed book.
1092    ///
1093    /// Books are cloned out of the cache inside a scoped borrow before publishing,
1094    /// so subscribers can mutably borrow the cache (e.g. a strategy submitting an
1095    /// order from `on_book`).
1096    pub fn snapshot(&self, _event: TimeEvent) {
1097        let snapshot_infos: Vec<BookSnapshotInfo> =
1098            self.snapshot_infos.borrow().values().cloned().collect();
1099
1100        log::debug!(
1101            "BookSnapshotter.snapshot called for {} subscriptions at {}ms",
1102            snapshot_infos.len(),
1103            self.interval_ms,
1104        );
1105
1106        let books: Vec<(MStr<Topic>, OrderBook)> = {
1107            let cache = self.cache.borrow();
1108            let mut books = Vec::new();
1109
1110            for snap_info in &snapshot_infos {
1111                self.collect_snapshot(snap_info, &cache, &mut books);
1112            }
1113
1114            books
1115        };
1116
1117        for (topic, book) in books {
1118            msgbus::publish_book(topic, &book);
1119        }
1120    }
1121
1122    fn collect_snapshot(
1123        &self,
1124        snap_info: &BookSnapshotInfo,
1125        cache: &Cache,
1126        books: &mut Vec<(MStr<Topic>, OrderBook)>,
1127    ) {
1128        if let Some((root, class)) = snap_info.parent {
1129            let topic = snap_info.topic;
1130            for instrument in cache.instruments_by_parent(&snap_info.venue, &root, class) {
1131                self.collect_order_book(&instrument.id(), topic, cache, books);
1132            }
1133        } else {
1134            self.collect_order_book(&snap_info.instrument_id, snap_info.topic, cache, books);
1135        }
1136    }
1137
1138    fn collect_order_book(
1139        &self,
1140        instrument_id: &InstrumentId,
1141        topic: MStr<Topic>,
1142        cache: &Cache,
1143        books: &mut Vec<(MStr<Topic>, OrderBook)>,
1144    ) {
1145        let book = match cache.try_order_book(instrument_id) {
1146            Ok(book) => book,
1147            Err(e) => {
1148                log::error!("Cannot publish OrderBook snapshot: {e}");
1149                return;
1150            }
1151        };
1152
1153        if book.update_count == 0 {
1154            log::debug!("OrderBook not yet updated for snapshot: {instrument_id}");
1155            return;
1156        }
1157        log::debug!(
1158            "Publishing OrderBook snapshot for {instrument_id} (update_count={})",
1159            book.update_count
1160        );
1161
1162        books.push((topic, book.clone()));
1163    }
1164}
1165
1166// Resolves parent expansion components for a book subscription command.
1167//
1168// Returns Ok(Some((root, class))) when params carries PARAMS_IS_PARENT=true and
1169// the instrument_id parses as a recognized <root>.<class> shape; Ok(None) for
1170// concrete (non-parent) subscriptions; Err when the caller asserts a parent
1171// subscription but the id cannot be parsed, so subscribe entries can reject up
1172// front before touching state.
1173fn resolve_parent_components(
1174    instrument_id: &InstrumentId,
1175    params: Option<&Params>,
1176) -> anyhow::Result<Option<(Ustr, InstrumentClass)>> {
1177    if !is_parent_subscription(params) {
1178        return Ok(None);
1179    }
1180
1181    let Some((root, class)) = instrument_id.parse_parent_components() else {
1182        anyhow::bail!(
1183            "Cannot expand parent subscription for {instrument_id}: \
1184             symbol does not parse as `<root>.<class>` with a recognized class suffix"
1185        );
1186    };
1187
1188    Ok(Some((Ustr::from(root), class)))
1189}
1190
1191#[cfg(test)]
1192mod tests {
1193    use nautilus_common::msgbus::TypedHandler;
1194    use nautilus_core::{UUID4, UnixNanos};
1195    use nautilus_model::{
1196        data::BookOrder,
1197        enums::{BookType, OrderSide},
1198        types::{Price, Quantity},
1199    };
1200    use rstest::rstest;
1201
1202    use super::*;
1203
1204    #[rstest]
1205    fn snapshot_skips_missing_order_book() {
1206        let instrument_id = InstrumentId::from("AUD/USD.SIM");
1207        let interval_ms = NonZeroUsize::new(100).unwrap();
1208        let topic = switchboard::get_book_snapshots_topic(instrument_id, interval_ms);
1209        let snapshot_infos = Rc::new(RefCell::new(IndexMap::new()));
1210
1211        snapshot_infos.borrow_mut().insert(
1212            instrument_id,
1213            BookSnapshotInfo {
1214                instrument_id,
1215                venue: Venue::new("SIM"),
1216                parent: None,
1217                topic,
1218                interval_ms,
1219            },
1220        );
1221
1222        let snapshotter = BookSnapshotter::new(
1223            interval_ms,
1224            snapshot_infos,
1225            Rc::new(RefCell::new(Cache::default())),
1226        );
1227        let event = TimeEvent::new(
1228            Ustr::from("TEST"),
1229            UUID4::new(),
1230            UnixNanos::default(),
1231            UnixNanos::default(),
1232        );
1233
1234        snapshotter.snapshot(event);
1235    }
1236
1237    #[rstest]
1238    fn snapshot_allows_subscriber_to_mutably_borrow_cache() {
1239        let instrument_id = InstrumentId::from("AUD/USD.SIM");
1240        let interval_ms = NonZeroUsize::new(100).unwrap();
1241        let topic = switchboard::get_book_snapshots_topic(instrument_id, interval_ms);
1242        let snapshot_infos = Rc::new(RefCell::new(IndexMap::new()));
1243
1244        snapshot_infos.borrow_mut().insert(
1245            instrument_id,
1246            BookSnapshotInfo {
1247                instrument_id,
1248                venue: Venue::new("SIM"),
1249                parent: None,
1250                topic,
1251                interval_ms,
1252            },
1253        );
1254
1255        let cache = Rc::new(RefCell::new(Cache::default()));
1256        let mut book = OrderBook::new(instrument_id, BookType::L2_MBP);
1257        book.add(
1258            BookOrder::new(OrderSide::Buy, Price::from("100.00"), Quantity::from(10), 0),
1259            0,
1260            1,
1261            UnixNanos::default(),
1262        );
1263        cache.borrow_mut().add_order_book(book).unwrap();
1264
1265        let received = Rc::new(RefCell::new(Vec::new()));
1266        let handler = CacheWritingBookHandler {
1267            id: Ustr::from("CacheWritingBookHandler"),
1268            cache: Rc::clone(&cache),
1269            received: Rc::clone(&received),
1270        };
1271        msgbus::subscribe_book_snapshots(topic.into(), TypedHandler::new(handler), None);
1272
1273        let snapshotter = BookSnapshotter::new(interval_ms, snapshot_infos, cache);
1274        let event = TimeEvent::new(
1275            Ustr::from("TEST"),
1276            UUID4::new(),
1277            UnixNanos::default(),
1278            UnixNanos::default(),
1279        );
1280
1281        snapshotter.snapshot(event);
1282
1283        let received = received.borrow();
1284        assert_eq!(received.len(), 1);
1285        assert_eq!(received[0].instrument_id, instrument_id);
1286        assert_eq!(received[0].best_bid_price(), Some(Price::from("100.00")));
1287    }
1288
1289    #[rstest]
1290    fn snapshot_skips_book_with_no_updates() {
1291        let instrument_id = InstrumentId::from("AUD/USD.SIM");
1292        let interval_ms = NonZeroUsize::new(100).unwrap();
1293        let topic = switchboard::get_book_snapshots_topic(instrument_id, interval_ms);
1294        let snapshot_infos = Rc::new(RefCell::new(IndexMap::new()));
1295
1296        snapshot_infos.borrow_mut().insert(
1297            instrument_id,
1298            BookSnapshotInfo {
1299                instrument_id,
1300                venue: Venue::new("SIM"),
1301                parent: None,
1302                topic,
1303                interval_ms,
1304            },
1305        );
1306
1307        let cache = Rc::new(RefCell::new(Cache::default()));
1308        cache
1309            .borrow_mut()
1310            .add_order_book(OrderBook::new(instrument_id, BookType::L2_MBP))
1311            .unwrap();
1312
1313        let received = Rc::new(RefCell::new(Vec::new()));
1314        let handler = CacheWritingBookHandler {
1315            id: Ustr::from("CacheWritingBookHandler-NoUpdates"),
1316            cache: Rc::clone(&cache),
1317            received: Rc::clone(&received),
1318        };
1319        msgbus::subscribe_book_snapshots(topic.into(), TypedHandler::new(handler), None);
1320
1321        let snapshotter = BookSnapshotter::new(interval_ms, snapshot_infos, cache);
1322        let event = TimeEvent::new(
1323            Ustr::from("TEST"),
1324            UUID4::new(),
1325            UnixNanos::default(),
1326            UnixNanos::default(),
1327        );
1328
1329        snapshotter.snapshot(event);
1330
1331        assert!(received.borrow().is_empty());
1332    }
1333
1334    struct CacheWritingBookHandler {
1335        id: Ustr,
1336        cache: Rc<RefCell<Cache>>,
1337        received: Rc<RefCell<Vec<OrderBook>>>,
1338    }
1339
1340    impl Handler<OrderBook> for CacheWritingBookHandler {
1341        fn id(&self) -> Ustr {
1342            self.id
1343        }
1344
1345        fn handle(&self, book: &OrderBook) {
1346            // Mirrors a strategy writing to the cache from `on_book`
1347            let mut cache = self.cache.borrow_mut();
1348            let _ = cache.order_book_mut(&book.instrument_id);
1349            self.received.borrow_mut().push(book.clone());
1350        }
1351    }
1352}