1use 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 #[must_use]
46 pub fn subscribed_book_deltas(&self) -> Vec<InstrumentId> {
47 self.collect_subscriptions(|client| &client.subscriptions_book_deltas)
48 }
49
50 #[must_use]
52 pub fn subscribed_book_depth(&self) -> Vec<InstrumentId> {
53 self.collect_subscriptions(|client| &client.subscriptions_book_depth)
54 }
55
56 #[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 #[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, 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 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 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#[derive(Clone, Debug)]
862pub struct BookSnapshotInfo {
863 pub instrument_id: InstrumentId,
864 pub venue: Venue,
865 pub parent: Option<(Ustr, InstrumentClass)>,
868 pub topic: MStr<Topic>,
869 pub interval_ms: NonZeroUsize,
870}
871
872pub(crate) type BookSnapshotInfos = Rc<RefCell<IndexMap<InstrumentId, BookSnapshotInfo>>>;
877
878pub(crate) type BookSnapshotKey = (InstrumentId, NonZeroUsize);
880
881pub(crate) enum BookSnapshotUnsubscribeResult {
883 NotSubscribed,
885 Decremented,
887 Removed,
889}
890
891pub(crate) type BookDeltasKey = (InstrumentId, Option<ClientId>, Option<Venue>);
893
894pub(crate) enum BookDeltasUnsubscribeResult {
896 NotSubscribed,
898 Decremented,
900 Removed,
902}
903
904#[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 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
1010pub(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("e.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, "e);
1038}
1039
1040#[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 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 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
1145fn 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 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}