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(|params| IndexMap::clone(params))
343            .unwrap_or_default();
344        params.shift_remove(PARAMS_IS_PARENT);
345
346        for active in subscription
347            .targets
348            .iter()
349            .filter_map(|id| self.book_subscriptions.get(id))
350            .flat_map(|book| &book.owners)
351        {
352            if !subscription.managed()
353                && !active.managed()
354                && subscription.client_id != active.client_id
355            {
356                continue;
357            }
358
359            if subscription.is_depth() != active.is_depth() {
360                anyhow::ensure!(
361                    !subscription.managed() || !active.managed(),
362                    "Conflicting managed book source for {instrument_id}: deltas and depth cannot both manage the same book; use managed=false for the other subscription"
363                );
364                continue;
365            }
366
367            let mut active_params = active
368                .command
369                .params()
370                .map(|params| IndexMap::clone(params))
371                .unwrap_or_default();
372            active_params.shift_remove(PARAMS_IS_PARENT);
373            anyhow::ensure!(
374                subscription.client_id == active.client_id
375                    && subscription.config() == active.config()
376                    && params == active_params,
377                "Conflicting book subscription for {instrument_id}: shared book sources must use the same client, book type, depth, and parameters"
378            );
379        }
380
381        if subscription.managed() {
382            self.setup_book_updater(
383                &subscription.targets,
384                subscription.config().0,
385                subscription.is_depth(),
386            )?;
387        }
388
389        for target_id in &subscription.targets {
390            self.book_subscriptions
391                .entry(*target_id)
392                .or_default()
393                .owners
394                .push(Rc::clone(&subscription));
395        }
396
397        self.book_subscription_owners
398            .entry(instrument_id)
399            .or_default()
400            .push(subscription);
401        Ok(())
402    }
403
404    pub(super) fn release_book_subscription(&mut self, command: &UnsubscribeCommand) -> bool {
405        let key = SubscriptionKey::from_unsubscribe(command);
406
407        let instrument_id = match command {
408            UnsubscribeCommand::BookDeltas(cmd) => cmd
409                .single_instrument_id()
410                .expect("book commands are projected onto one instrument"),
411            UnsubscribeCommand::BookDepth(cmd) => cmd
412                .single_instrument_id()
413                .expect("book commands are projected onto one instrument"),
414            UnsubscribeCommand::BookSnapshots(cmd) => cmd
415                .single_instrument_id()
416                .expect("book commands are projected onto one instrument"),
417            _ => unreachable!("only book subscriptions are released"),
418        };
419
420        let Some(owners) = self.book_subscription_owners.get_mut(&instrument_id) else {
421            return false;
422        };
423
424        let index = owners.iter().position(|subscription| {
425            SubscriptionKey::from_subscribe(&subscription.command) == key
426                && subscription.command.client_id() == command.client_id()
427                && subscription.command.venue() == command.venue()
428                && command
429                    .correlation_id()
430                    .is_none_or(|id| subscription.command.command_id() == id)
431        });
432
433        let Some(index) = index else {
434            return false;
435        };
436
437        let subscription = owners.remove(index);
438        if owners.is_empty() {
439            self.book_subscription_owners.remove(&instrument_id);
440        }
441
442        for &target_id in &subscription.targets {
443            let book = self
444                .book_subscriptions
445                .get_mut(&target_id)
446                .expect("retained book subscription");
447            book.owners
448                .retain(|owner| !Rc::ptr_eq(owner, &subscription));
449            let managed = book.owners.iter().any(|owner| owner.managed());
450            if book.owners.is_empty() {
451                self.book_subscriptions.remove(&target_id);
452            }
453
454            if managed {
455                continue;
456            }
457
458            let Some(updater) = self.book_updaters.remove(&target_id) else {
459                continue;
460            };
461
462            let deltas_handler: TypedHandler<OrderBookDeltas> =
463                TypedHandler::new(Rc::clone(&updater));
464            let depth_handler: TypedHandler<OrderBookDepth> = TypedHandler::new(updater);
465            msgbus::unsubscribe_book_deltas(
466                switchboard::get_book_deltas_topic(target_id).into(),
467                &deltas_handler,
468            );
469            msgbus::unsubscribe_book_depth(
470                switchboard::get_book_depth_topic(target_id).into(),
471                &depth_handler,
472            );
473        }
474
475        true
476    }
477
478    fn has_book_snapshot_subscriptions(&self, instrument_id: &InstrumentId) -> bool {
479        self.book_snapshot_counts
480            .keys()
481            .any(|(id, _)| id == instrument_id)
482    }
483
484    fn has_book_delta_subscription_key(
485        &self,
486        instrument_id: InstrumentId,
487        client_id: Option<ClientId>,
488        venue: Option<Venue>,
489    ) -> bool {
490        self.book_deltas_counts
491            .contains_key(&(instrument_id, client_id, venue))
492    }
493
494    fn has_book_depth_subscription_key(
495        &self,
496        instrument_id: InstrumentId,
497        client_id: Option<ClientId>,
498        venue: Option<Venue>,
499    ) -> bool {
500        self.book_depth_counts
501            .contains_key(&(instrument_id, client_id, venue))
502    }
503
504    fn increment_book_delta_subscription(
505        &mut self,
506        instrument_id: InstrumentId,
507        client_id: Option<ClientId>,
508        venue: Option<Venue>,
509    ) {
510        let key = (instrument_id, client_id, venue);
511
512        if let Some(count) = self.book_deltas_counts.get_mut(&key) {
513            *count += 1;
514        } else {
515            self.book_deltas_counts.insert(key, 1);
516        }
517    }
518
519    fn decrement_book_delta_subscription(
520        &mut self,
521        instrument_id: InstrumentId,
522        client_id: Option<ClientId>,
523        venue: Option<Venue>,
524    ) -> BookDeltasUnsubscribeResult {
525        let key = (instrument_id, client_id, venue);
526
527        let Some(count) = self.book_deltas_counts.get_mut(&key) else {
528            return BookDeltasUnsubscribeResult::NotSubscribed;
529        };
530
531        if *count > 1 {
532            *count -= 1;
533            return BookDeltasUnsubscribeResult::Decremented;
534        }
535
536        self.book_deltas_counts.shift_remove(&key);
537        BookDeltasUnsubscribeResult::Removed
538    }
539
540    fn increment_book_depth_subscription(
541        &mut self,
542        instrument_id: InstrumentId,
543        client_id: Option<ClientId>,
544        venue: Option<Venue>,
545    ) {
546        let key = (instrument_id, client_id, venue);
547        *self.book_depth_counts.entry(key).or_insert(0) += 1;
548    }
549
550    fn decrement_book_depth_subscription(
551        &mut self,
552        instrument_id: InstrumentId,
553        client_id: Option<ClientId>,
554        venue: Option<Venue>,
555    ) -> BookDeltasUnsubscribeResult {
556        let key = (instrument_id, client_id, venue);
557
558        let Some(count) = self.book_depth_counts.get_mut(&key) else {
559            return BookDeltasUnsubscribeResult::NotSubscribed;
560        };
561
562        if *count > 1 {
563            *count -= 1;
564            return BookDeltasUnsubscribeResult::Decremented;
565        }
566
567        self.book_depth_counts.shift_remove(&key);
568        BookDeltasUnsubscribeResult::Removed
569    }
570
571    fn increment_book_snapshot_subscription(
572        &mut self,
573        cmd: &SubscribeBookSnapshots,
574        parent: Option<(Ustr, InstrumentClass)>,
575    ) -> bool {
576        let instrument_id = cmd
577            .single_instrument_id()
578            .expect("instrument command has one member at this boundary");
579        let key = (instrument_id, cmd.interval_ms);
580
581        if let Some(count) = self.book_snapshot_counts.get_mut(&key) {
582            *count += 1;
583            return false;
584        }
585
586        self.book_snapshot_counts.insert(key, 1);
587
588        let snapshot_infos = if let Some(snapshot_infos) = self.book_intervals.get(&cmd.interval_ms)
589        {
590            Rc::clone(snapshot_infos)
591        } else {
592            let snapshot_infos = Rc::new(RefCell::new(IndexMap::new()));
593            self.book_intervals
594                .insert(cmd.interval_ms, Rc::clone(&snapshot_infos));
595            self.schedule_book_snapshotter(cmd.interval_ms, Rc::clone(&snapshot_infos));
596            snapshot_infos
597        };
598
599        let topic = switchboard::get_book_snapshots_topic(instrument_id, cmd.interval_ms);
600
601        let snap_info = BookSnapshotInfo {
602            instrument_id,
603            venue: instrument_id.venue,
604            parent,
605            topic,
606            interval_ms: cmd.interval_ms,
607        };
608
609        snapshot_infos.borrow_mut().insert(instrument_id, snap_info);
610
611        true
612    }
613
614    fn decrement_book_snapshot_subscription(
615        &mut self,
616        instrument_id: InstrumentId,
617        interval_ms: NonZeroUsize,
618    ) -> BookSnapshotUnsubscribeResult {
619        let key = (instrument_id, interval_ms);
620
621        let Some(count) = self.book_snapshot_counts.get_mut(&key) else {
622            return BookSnapshotUnsubscribeResult::NotSubscribed;
623        };
624
625        if *count > 1 {
626            *count -= 1;
627            return BookSnapshotUnsubscribeResult::Decremented;
628        }
629
630        self.book_snapshot_counts.shift_remove(&key);
631
632        let remove_interval = if let Some(snapshot_infos) = self.book_intervals.get(&interval_ms) {
633            let mut snapshot_infos = snapshot_infos.borrow_mut();
634            snapshot_infos.shift_remove(&instrument_id);
635            snapshot_infos.is_empty()
636        } else {
637            false
638        };
639
640        if remove_interval {
641            self.book_intervals.remove(&interval_ms);
642
643            if let Some(snapshotter) = self.book_snapshotters.remove(&interval_ms) {
644                let timer_name = snapshotter.timer_name;
645                let mut clock = self.clock.borrow_mut();
646                if clock.timer_exists(&timer_name) {
647                    clock.cancel_timer(&timer_name);
648                }
649            }
650        }
651
652        BookSnapshotUnsubscribeResult::Removed
653    }
654
655    fn schedule_book_snapshotter(
656        &mut self,
657        interval_ms: NonZeroUsize,
658        snapshot_infos: BookSnapshotInfos,
659    ) {
660        let interval_ms_u64 =
661            u64::try_from(interval_ms.get()).expect("Snapshot interval exceeds u64");
662        let interval_ns = DurationNanos::from_millis(interval_ms_u64);
663        let now_ns = self.clock.borrow().timestamp_ns();
664        let start_time_ns = now_ns
665            .floor(interval_ns)
666            .checked_add(interval_ns)
667            .expect("Book snapshot timer start exceeds UnixNanos range");
668
669        let snapshotter = Rc::new(BookSnapshotter::new(
670            interval_ms,
671            snapshot_infos,
672            Rc::clone(&self.cache),
673        ));
674        let timer_name = snapshotter.timer_name;
675        let snapshotter_callback = Rc::clone(&snapshotter);
676        let callback_fn: Rc<dyn Fn(TimeEvent)> =
677            Rc::new(move |event| snapshotter_callback.snapshot(event));
678        let callback = TimeEventCallback::from(callback_fn);
679
680        self.clock
681            .borrow_mut()
682            .set_timer_ns(
683                &timer_name,
684                interval_ns,
685                Some(start_time_ns),
686                None,
687                Some(callback),
688                None,
689                None,
690            )
691            .expect(FAILED);
692
693        self.book_snapshotters.insert(interval_ms, snapshotter);
694    }
695
696    // Skip cache writes that would regress a book a `BookUpdater` is maintaining.
697    // Unmanaged subscriptions don't install a `BookUpdater`, so they don't gate writes.
698    fn cache_is_owned_by_live_subscription(&self, instrument_id: &InstrumentId) -> bool {
699        self.book_updaters.contains_key(instrument_id)
700    }
701
702    pub(super) fn handle_book_response(&self, book: &OrderBook) {
703        if self.cache_is_owned_by_live_subscription(&book.instrument_id) {
704            log::debug!(
705                "Skipping cache write for order book {}: live subscription owns the book",
706                book.instrument_id,
707            );
708            return;
709        }
710
711        log::debug!("Adding order book {} to cache", book.instrument_id);
712
713        if let Err(e) = self
714            .cache
715            .as_ref()
716            .borrow_mut()
717            .add_order_book(book.clone())
718        {
719            log_error_on_cache_insert(&e);
720        }
721    }
722
723    pub(super) fn handle_book_deltas_response(&self, resp: &BookDeltasResponse) {
724        if !self.cache_is_owned_by_live_subscription(&resp.instrument_id) {
725            let mut cache = self.cache.as_ref().borrow_mut();
726            if let Some(book) = cache.order_book_mut(&resp.instrument_id) {
727                for delta in resp.data.iter() {
728                    if let Err(e) = book.apply_delta(delta) {
729                        log::error!("Failed to apply historical delta to cache: {e}");
730                    }
731                }
732            } else {
733                log::debug!(
734                    "Skipping cache write for {} historical deltas on {}: no cache book yet",
735                    resp.data.len(),
736                    resp.instrument_id,
737                );
738            }
739        }
740
741        // Group deltas by `F_LAST` so each published batch preserves the original event
742        // boundary and metadata (timestamps and sequence from the closing delta), matching
743        // the live `handle_delta` buffering semantic. Collapsing the whole response into
744        // one batch would surface a synthetic event with the trailing delta's flags only.
745        if resp.data.is_empty() {
746            return;
747        }
748
749        let topic = switchboard::get_pipeline_book_deltas_topic(resp.instrument_id);
750        let mut frame: Vec<OrderBookDelta> = Vec::new();
751        for delta in resp.data.iter() {
752            frame.push(*delta);
753            if RecordFlag::F_LAST.matches(delta.flags) {
754                let batch = OrderBookDeltas::new(resp.instrument_id, std::mem::take(&mut frame));
755                msgbus::publish_deltas(topic, &batch);
756            }
757        }
758
759        if !frame.is_empty() {
760            let batch = OrderBookDeltas::new(resp.instrument_id, frame);
761            msgbus::publish_deltas(topic, &batch);
762        }
763    }
764
765    pub(super) fn handle_book_depth_response(&self, resp: &BookDepthResponse) {
766        let topic = switchboard::get_pipeline_book_depth_topic(resp.instrument_id);
767        for depth in resp.data.iter() {
768            msgbus::publish_depth(topic, depth);
769        }
770    }
771
772    fn setup_book_updater(
773        &mut self,
774        target_ids: &[InstrumentId],
775        book_type: BookType,
776        depth: bool,
777    ) -> anyhow::Result<()> {
778        {
779            let mut cache = self.cache.borrow_mut();
780            for target_id in target_ids {
781                if cache
782                    .order_book(target_id)
783                    .is_none_or(|book| book.book_type != book_type)
784                {
785                    cache.add_order_book(OrderBook::new(*target_id, book_type))?;
786                }
787            }
788        }
789
790        for target_id in target_ids {
791            let updater = Rc::clone(self.book_updaters.entry(*target_id).or_insert_with(|| {
792                Rc::new(BookUpdater::new(
793                    target_id,
794                    Rc::clone(&self.cache),
795                    self.config.emit_quotes_from_book,
796                ))
797            }));
798
799            if depth {
800                msgbus::subscribe_book_depth(
801                    switchboard::get_book_depth_topic(*target_id).into(),
802                    TypedHandler::new(updater),
803                    Some(self.msgbus_priority),
804                );
805            } else {
806                msgbus::subscribe_book_deltas(
807                    switchboard::get_book_deltas_topic(*target_id).into(),
808                    TypedHandler::new(updater),
809                    Some(self.msgbus_priority),
810                );
811            }
812        }
813
814        Ok(())
815    }
816}
817
818#[derive(Debug, Default)]
819pub(super) struct BookSubscription {
820    pub(super) owners: Vec<Rc<BookSubscriptionOwner>>,
821}
822
823#[derive(Debug)]
824pub(super) struct BookSubscriptionOwner {
825    pub(super) command: SubscribeCommand,
826    pub(super) client_id: Option<ClientId>,
827    pub(super) targets: Vec<InstrumentId>,
828}
829
830impl BookSubscriptionOwner {
831    pub(super) fn managed(&self) -> bool {
832        match &self.command {
833            SubscribeCommand::BookDeltas(cmd) => cmd.managed,
834            SubscribeCommand::BookDepth(cmd) => cmd.managed,
835            SubscribeCommand::BookSnapshots(_) => true,
836            _ => unreachable!("only book subscriptions are retained"),
837        }
838    }
839
840    pub(super) fn is_depth(&self) -> bool {
841        matches!(self.command, SubscribeCommand::BookDepth(_))
842    }
843
844    pub(super) fn config(&self) -> (BookType, Option<NonZeroUsize>) {
845        match &self.command {
846            SubscribeCommand::BookDeltas(cmd) => (cmd.book_type, cmd.depth),
847            SubscribeCommand::BookDepth(cmd) => (cmd.book_type, cmd.depth),
848            SubscribeCommand::BookSnapshots(cmd) => (cmd.book_type, cmd.depth),
849            _ => unreachable!("only book subscriptions are retained"),
850        }
851    }
852}
853
854#[derive(Clone, Debug)]
855pub(super) struct BookSnapshotSource {
856    pub(super) command: SubscribeBookSnapshots,
857    pub(super) client_command: SubscribeCommand,
858}
859
860/// Contains information for creating snapshots of specific order books.
861#[derive(Clone, Debug)]
862pub struct BookSnapshotInfo {
863    pub instrument_id: InstrumentId,
864    pub venue: Venue,
865    /// Parent expansion components `(root, class)` when this snapshot subscription
866    /// targets a parent symbol. `None` for concrete (exact-instrument) subscriptions.
867    pub parent: Option<(Ustr, InstrumentClass)>,
868    pub topic: MStr<Topic>,
869    pub interval_ms: NonZeroUsize,
870}
871
872/// Reference-counted map of per-instrument book snapshot descriptors.
873///
874/// Shared between the engine (which populates it on subscribe) and the
875/// [`BookSnapshotter`] timer callback (which iterates it on each tick).
876pub(crate) type BookSnapshotInfos = Rc<RefCell<IndexMap<InstrumentId, BookSnapshotInfo>>>;
877
878/// Reference count key for a book snapshot subscription.
879pub(crate) type BookSnapshotKey = (InstrumentId, NonZeroUsize);
880
881/// Outcome of decrementing a book snapshot subscription.
882pub(crate) enum BookSnapshotUnsubscribeResult {
883    /// No matching subscription was found.
884    NotSubscribed,
885    /// The reference count was decremented but other consumers remain.
886    Decremented,
887    /// The last consumer was removed; tear down associated state.
888    Removed,
889}
890
891/// Reference count key for a book deltas subscription.
892pub(crate) type BookDeltasKey = (InstrumentId, Option<ClientId>, Option<Venue>);
893
894/// Outcome of decrementing a book deltas subscription.
895pub(crate) enum BookDeltasUnsubscribeResult {
896    /// No matching subscription was found.
897    NotSubscribed,
898    /// The reference count was decremented but other consumers remain.
899    Decremented,
900    /// The last consumer was removed; tear down associated state.
901    Removed,
902}
903
904/// Handles order book updates and delta processing for a specific instrument.
905///
906/// The `BookUpdater` processes incoming order book deltas and maintains
907/// the current state of an order book. It can handle both incremental
908/// updates and full snapshots for the instrument it's assigned to.
909/// When `emit_quotes_from_book` is enabled, derived quotes use the book's last
910/// event time for `ts_event` and the incoming update's `ts_init`.
911#[derive(Debug)]
912pub struct BookUpdater {
913    pub id: Ustr,
914    pub instrument_id: InstrumentId,
915    pub cache: Rc<RefCell<Cache>>,
916    pub emit_quotes_from_book: bool,
917}
918
919impl BookUpdater {
920    /// Creates a new [`BookUpdater`] instance.
921    pub fn new(
922        instrument_id: &InstrumentId,
923        cache: Rc<RefCell<Cache>>,
924        emit_quotes_from_book: bool,
925    ) -> Self {
926        Self {
927            id: Ustr::from(&format!("{}-{}", stringify!(BookUpdater), instrument_id)),
928            instrument_id: *instrument_id,
929            cache,
930            emit_quotes_from_book,
931        }
932    }
933}
934
935impl Handler<OrderBookDeltas> for BookUpdater {
936    fn id(&self) -> Ustr {
937        self.id
938    }
939
940    fn handle(&self, deltas: &OrderBookDeltas) {
941        let mut emit: Option<QuoteTick> = None;
942        {
943            let mut cache = self.cache.borrow_mut();
944            if let Some(book) = cache.order_book_mut(&deltas.instrument_id) {
945                if let Err(e) = book.apply_deltas(deltas) {
946                    log::error!("Failed to apply deltas: {e}");
947                    return;
948                }
949
950                if self.emit_quotes_from_book {
951                    emit = derive_quote_from_book(book, deltas.ts_init);
952                }
953            }
954        }
955
956        if let Some(quote) = emit {
957            publish_quote_if_changed(&self.cache, quote);
958        }
959    }
960}
961
962impl Handler<OrderBookDepth> for BookUpdater {
963    fn id(&self) -> Ustr {
964        self.id
965    }
966
967    fn handle(&self, depth: &OrderBookDepth) {
968        let mut emit: Option<QuoteTick> = None;
969        {
970            let mut cache = self.cache.borrow_mut();
971            if let Some(book) = cache.order_book_mut(&depth.instrument_id) {
972                if let Err(e) = book.apply_depth(depth) {
973                    log::error!("Failed to apply depth: {e}");
974                    return;
975                }
976
977                if self.emit_quotes_from_book {
978                    emit = derive_quote_from_book(book, depth.ts_init);
979                }
980            }
981        }
982
983        if let Some(quote) = emit {
984            publish_quote_if_changed(&self.cache, quote);
985        }
986    }
987}
988
989fn derive_quote_from_book(book: &OrderBook, ts_init: UnixNanos) -> Option<QuoteTick> {
990    let bid_price = book.best_bid_price()?;
991    let ask_price = book.best_ask_price()?;
992    let bid_size = book.best_bid_size()?;
993    let ask_size = book.best_ask_size()?;
994
995    if bid_size.is_zero() || ask_size.is_zero() {
996        return None;
997    }
998
999    Some(QuoteTick::new(
1000        book.instrument_id,
1001        bid_price,
1002        ask_price,
1003        bid_size,
1004        ask_size,
1005        book.ts_last,
1006        ts_init,
1007    ))
1008}
1009
1010/// Publishes the derived `QuoteTick` if top-of-book changed.
1011///
1012/// Writes to cache and republishes only when bid/ask price or size differs
1013/// from the cached quote.
1014pub(crate) fn publish_quote_if_changed(cache: &Rc<RefCell<Cache>>, quote: QuoteTick) {
1015    let publish = {
1016        let cache_ref = cache.borrow();
1017        match cache_ref.quote(&quote.instrument_id) {
1018            None => true,
1019            Some(last) => {
1020                last.bid_price != quote.bid_price
1021                    || last.ask_price != quote.ask_price
1022                    || last.bid_size != quote.bid_size
1023                    || last.ask_size != quote.ask_size
1024            }
1025        }
1026    };
1027
1028    if !publish {
1029        return;
1030    }
1031
1032    if let Err(e) = cache.borrow_mut().add_quote(quote) {
1033        log::error!("Error on cache insert: {e}");
1034    }
1035
1036    let topic = switchboard::get_quotes_topic(quote.instrument_id);
1037    msgbus::publish_quote(topic, &quote);
1038}
1039
1040/// Creates periodic snapshots of order books at configured intervals.
1041///
1042/// The `BookSnapshotter` generates order book snapshots on timer events,
1043/// publishing them as market data. This is useful for providing periodic
1044/// full order book state updates in addition to incremental delta updates.
1045#[derive(Debug)]
1046pub struct BookSnapshotter {
1047    pub timer_name: Ustr,
1048    pub interval_ms: NonZeroUsize,
1049    pub snapshot_infos: Rc<RefCell<IndexMap<InstrumentId, BookSnapshotInfo>>>,
1050    pub cache: Rc<RefCell<Cache>>,
1051}
1052
1053impl BookSnapshotter {
1054    /// Creates a new [`BookSnapshotter`] instance.
1055    pub fn new(
1056        interval_ms: NonZeroUsize,
1057        snapshot_infos: Rc<RefCell<IndexMap<InstrumentId, BookSnapshotInfo>>>,
1058        cache: Rc<RefCell<Cache>>,
1059    ) -> Self {
1060        let timer_name = format!("OrderBookSnapshots|{interval_ms}");
1061
1062        Self {
1063            timer_name: Ustr::from(&timer_name),
1064            interval_ms,
1065            snapshot_infos,
1066            cache,
1067        }
1068    }
1069
1070    /// Publishes a snapshot for each subscribed book.
1071    ///
1072    /// Books are cloned out of the cache inside a scoped borrow before publishing,
1073    /// so subscribers can mutably borrow the cache (e.g. a strategy submitting an
1074    /// order from `on_book`).
1075    pub fn snapshot(&self, _event: TimeEvent) {
1076        let snapshot_infos: Vec<BookSnapshotInfo> =
1077            self.snapshot_infos.borrow().values().cloned().collect();
1078
1079        log::debug!(
1080            "BookSnapshotter.snapshot called for {} subscriptions at {}ms",
1081            snapshot_infos.len(),
1082            self.interval_ms,
1083        );
1084
1085        let books: Vec<(MStr<Topic>, OrderBook)> = {
1086            let cache = self.cache.borrow();
1087            let mut books = Vec::new();
1088
1089            for snap_info in &snapshot_infos {
1090                self.collect_snapshot(snap_info, &cache, &mut books);
1091            }
1092
1093            books
1094        };
1095
1096        for (topic, book) in books {
1097            msgbus::publish_book(topic, &book);
1098        }
1099    }
1100
1101    fn collect_snapshot(
1102        &self,
1103        snap_info: &BookSnapshotInfo,
1104        cache: &Cache,
1105        books: &mut Vec<(MStr<Topic>, OrderBook)>,
1106    ) {
1107        if let Some((root, class)) = snap_info.parent {
1108            let topic = snap_info.topic;
1109            for instrument in cache.instruments_by_parent(&snap_info.venue, &root, class) {
1110                self.collect_order_book(&instrument.id(), topic, cache, books);
1111            }
1112        } else {
1113            self.collect_order_book(&snap_info.instrument_id, snap_info.topic, cache, books);
1114        }
1115    }
1116
1117    fn collect_order_book(
1118        &self,
1119        instrument_id: &InstrumentId,
1120        topic: MStr<Topic>,
1121        cache: &Cache,
1122        books: &mut Vec<(MStr<Topic>, OrderBook)>,
1123    ) {
1124        let book = match cache.try_order_book(instrument_id) {
1125            Ok(book) => book,
1126            Err(e) => {
1127                log::error!("Cannot publish OrderBook snapshot: {e}");
1128                return;
1129            }
1130        };
1131
1132        if book.update_count == 0 {
1133            log::debug!("OrderBook not yet updated for snapshot: {instrument_id}");
1134            return;
1135        }
1136        log::debug!(
1137            "Publishing OrderBook snapshot for {instrument_id} (update_count={})",
1138            book.update_count
1139        );
1140
1141        books.push((topic, book.clone()));
1142    }
1143}
1144
1145// Resolves parent expansion components for a book subscription command.
1146//
1147// Returns Ok(Some((root, class))) when params carries PARAMS_IS_PARENT=true and
1148// the instrument_id parses as a recognized <root>.<class> shape; Ok(None) for
1149// concrete (non-parent) subscriptions; Err when the caller asserts a parent
1150// subscription but the id cannot be parsed, so subscribe entries can reject up
1151// front before touching state.
1152fn resolve_parent_components(
1153    instrument_id: &InstrumentId,
1154    params: Option<&Params>,
1155) -> anyhow::Result<Option<(Ustr, InstrumentClass)>> {
1156    if !is_parent_subscription(params) {
1157        return Ok(None);
1158    }
1159
1160    let Some((root, class)) = instrument_id.parse_parent_components() else {
1161        anyhow::bail!(
1162            "Cannot expand parent subscription for {instrument_id}: \
1163             symbol does not parse as `<root>.<class>` with a recognized class suffix"
1164        );
1165    };
1166
1167    Ok(Some((Ustr::from(root), class)))
1168}
1169
1170#[cfg(test)]
1171mod tests {
1172    use nautilus_common::msgbus::TypedHandler;
1173    use nautilus_core::{UUID4, UnixNanos};
1174    use nautilus_model::{
1175        data::BookOrder,
1176        enums::{BookType, OrderSide},
1177        types::{Price, Quantity},
1178    };
1179    use rstest::rstest;
1180
1181    use super::*;
1182
1183    #[rstest]
1184    fn snapshot_skips_missing_order_book() {
1185        let instrument_id = InstrumentId::from("AUD/USD.SIM");
1186        let interval_ms = NonZeroUsize::new(100).unwrap();
1187        let topic = switchboard::get_book_snapshots_topic(instrument_id, interval_ms);
1188        let snapshot_infos = Rc::new(RefCell::new(IndexMap::new()));
1189
1190        snapshot_infos.borrow_mut().insert(
1191            instrument_id,
1192            BookSnapshotInfo {
1193                instrument_id,
1194                venue: Venue::new("SIM"),
1195                parent: None,
1196                topic,
1197                interval_ms,
1198            },
1199        );
1200
1201        let snapshotter = BookSnapshotter::new(
1202            interval_ms,
1203            snapshot_infos,
1204            Rc::new(RefCell::new(Cache::default())),
1205        );
1206        let event = TimeEvent::new(
1207            Ustr::from("TEST"),
1208            UUID4::new(),
1209            UnixNanos::default(),
1210            UnixNanos::default(),
1211        );
1212
1213        snapshotter.snapshot(event);
1214    }
1215
1216    #[rstest]
1217    fn snapshot_allows_subscriber_to_mutably_borrow_cache() {
1218        let instrument_id = InstrumentId::from("AUD/USD.SIM");
1219        let interval_ms = NonZeroUsize::new(100).unwrap();
1220        let topic = switchboard::get_book_snapshots_topic(instrument_id, interval_ms);
1221        let snapshot_infos = Rc::new(RefCell::new(IndexMap::new()));
1222
1223        snapshot_infos.borrow_mut().insert(
1224            instrument_id,
1225            BookSnapshotInfo {
1226                instrument_id,
1227                venue: Venue::new("SIM"),
1228                parent: None,
1229                topic,
1230                interval_ms,
1231            },
1232        );
1233
1234        let cache = Rc::new(RefCell::new(Cache::default()));
1235        let mut book = OrderBook::new(instrument_id, BookType::L2_MBP);
1236        book.add(
1237            BookOrder::new(OrderSide::Buy, Price::from("100.00"), Quantity::from(10), 0),
1238            0,
1239            1,
1240            UnixNanos::default(),
1241        );
1242        cache.borrow_mut().add_order_book(book).unwrap();
1243
1244        let received = Rc::new(RefCell::new(Vec::new()));
1245        let handler = CacheWritingBookHandler {
1246            id: Ustr::from("CacheWritingBookHandler"),
1247            cache: Rc::clone(&cache),
1248            received: Rc::clone(&received),
1249        };
1250        msgbus::subscribe_book_snapshots(topic.into(), TypedHandler::new(handler), None);
1251
1252        let snapshotter = BookSnapshotter::new(interval_ms, snapshot_infos, cache);
1253        let event = TimeEvent::new(
1254            Ustr::from("TEST"),
1255            UUID4::new(),
1256            UnixNanos::default(),
1257            UnixNanos::default(),
1258        );
1259
1260        snapshotter.snapshot(event);
1261
1262        let received = received.borrow();
1263        assert_eq!(received.len(), 1);
1264        assert_eq!(received[0].instrument_id, instrument_id);
1265        assert_eq!(received[0].best_bid_price(), Some(Price::from("100.00")));
1266    }
1267
1268    #[rstest]
1269    fn snapshot_skips_book_with_no_updates() {
1270        let instrument_id = InstrumentId::from("AUD/USD.SIM");
1271        let interval_ms = NonZeroUsize::new(100).unwrap();
1272        let topic = switchboard::get_book_snapshots_topic(instrument_id, interval_ms);
1273        let snapshot_infos = Rc::new(RefCell::new(IndexMap::new()));
1274
1275        snapshot_infos.borrow_mut().insert(
1276            instrument_id,
1277            BookSnapshotInfo {
1278                instrument_id,
1279                venue: Venue::new("SIM"),
1280                parent: None,
1281                topic,
1282                interval_ms,
1283            },
1284        );
1285
1286        let cache = Rc::new(RefCell::new(Cache::default()));
1287        cache
1288            .borrow_mut()
1289            .add_order_book(OrderBook::new(instrument_id, BookType::L2_MBP))
1290            .unwrap();
1291
1292        let received = Rc::new(RefCell::new(Vec::new()));
1293        let handler = CacheWritingBookHandler {
1294            id: Ustr::from("CacheWritingBookHandler-NoUpdates"),
1295            cache: Rc::clone(&cache),
1296            received: Rc::clone(&received),
1297        };
1298        msgbus::subscribe_book_snapshots(topic.into(), TypedHandler::new(handler), None);
1299
1300        let snapshotter = BookSnapshotter::new(interval_ms, snapshot_infos, cache);
1301        let event = TimeEvent::new(
1302            Ustr::from("TEST"),
1303            UUID4::new(),
1304            UnixNanos::default(),
1305            UnixNanos::default(),
1306        );
1307
1308        snapshotter.snapshot(event);
1309
1310        assert!(received.borrow().is_empty());
1311    }
1312
1313    struct CacheWritingBookHandler {
1314        id: Ustr,
1315        cache: Rc<RefCell<Cache>>,
1316        received: Rc<RefCell<Vec<OrderBook>>>,
1317    }
1318
1319    impl Handler<OrderBook> for CacheWritingBookHandler {
1320        fn id(&self) -> Ustr {
1321            self.id
1322        }
1323
1324        fn handle(&self, book: &OrderBook) {
1325            // Mirrors a strategy writing to the cache from `on_book`
1326            let mut cache = self.cache.borrow_mut();
1327            let _ = cache.order_book_mut(&book.instrument_id);
1328            self.received.borrow_mut().push(book.clone());
1329        }
1330    }
1331}