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_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 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 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 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#[derive(Clone, Debug)]
883pub struct BookSnapshotInfo {
884 pub instrument_id: InstrumentId,
885 pub venue: Venue,
886 pub parent: Option<(Ustr, InstrumentClass)>,
889 pub topic: MStr<Topic>,
890 pub interval_ms: NonZeroUsize,
891}
892
893pub(crate) type BookSnapshotInfos = Rc<RefCell<IndexMap<InstrumentId, BookSnapshotInfo>>>;
898
899pub(crate) type BookSnapshotKey = (InstrumentId, NonZeroUsize);
901
902pub(crate) enum BookSnapshotUnsubscribeResult {
904 NotSubscribed,
906 Decremented,
908 Removed,
910}
911
912pub(crate) type BookDeltasKey = (InstrumentId, Option<ClientId>, Option<Venue>);
914
915pub(crate) enum BookDeltasUnsubscribeResult {
917 NotSubscribed,
919 Decremented,
921 Removed,
923}
924
925#[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 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
1031pub(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("e.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, "e);
1059}
1060
1061#[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 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 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
1166fn 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 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}