Skip to main content

nautilus_data/engine/
dispatch.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16#[cfg(feature = "defi")]
17use nautilus_common::defi::cache::IntegrityError;
18
19use super::{
20    Bar, Cache, CustomData, DataEngine, Display, FundingRateUpdate, IndexPriceUpdate, Instrument,
21    InstrumentAny, InstrumentClose, InstrumentStatus, MarkPriceUpdate, MarketStatusAction,
22    OptionGreeks, OrderBookDelta, OrderBookDeltas, OrderBookDepth, QuoteTick, Rc, RecordFlag,
23    RefCell, TradeTick, book, mem, msgbus, switchboard,
24};
25
26impl DataEngine {
27    #[inline]
28    fn pipeline_cache_writes_allowed(&self) -> bool {
29        !self.config.disable_historical_cache
30    }
31
32    pub(crate) fn handle_instrument(&mut self, instrument: &InstrumentAny) {
33        if self.cache_instrument(instrument) {
34            self.publish_instrument(instrument);
35        }
36    }
37
38    pub(crate) fn cache_instrument(&self, instrument: &InstrumentAny) -> bool {
39        log::debug!("Handling instrument: {}", instrument.id());
40
41        if let Err(e) = self
42            .cache
43            .as_ref()
44            .borrow_mut()
45            .add_instrument(instrument.clone())
46        {
47            log_error_on_cache_insert(&e);
48
49            #[cfg(feature = "defi")]
50            if e.is::<IntegrityError>()
51                || nautilus_model::defi::currency::instrument_codes(instrument)
52                    .map_or(true, |codes| !codes.is_empty())
53            {
54                return false;
55            }
56        }
57
58        true
59    }
60
61    pub(crate) fn publish_instrument(&mut self, instrument: &InstrumentAny) {
62        let topic = switchboard::get_instrument_topic(instrument.id());
63        log::debug!("Publishing instrument to topic: {topic}");
64        msgbus::publish_instrument(topic, instrument);
65
66        self.update_option_chains(instrument);
67    }
68
69    pub(super) fn handle_delta(&mut self, delta: OrderBookDelta) {
70        let mut deltas = if self.config.buffer_deltas {
71            self.buffer_delta(delta);
72
73            if !RecordFlag::F_LAST.matches(delta.flags) {
74                return; // Not the last delta for event
75            }
76
77            self.buffered_deltas_map
78                .remove(&delta.instrument_id)
79                .expect("buffered deltas exist")
80        } else {
81            self.single_delta_batch(delta)
82        };
83
84        let topic = switchboard::get_book_deltas_topic(deltas.instrument_id);
85        msgbus::publish_deltas(topic, &deltas);
86        self.reclaim_deltas_frame(mem::take(&mut deltas.deltas));
87    }
88
89    pub(super) fn handle_deltas(&mut self, deltas: &OrderBookDeltas) {
90        if self.config.buffer_deltas {
91            let instrument_id = deltas.instrument_id;
92
93            for delta in &deltas.deltas {
94                let is_last = RecordFlag::F_LAST.matches(delta.flags);
95                self.buffer_delta(*delta);
96
97                if is_last {
98                    let mut deltas_to_publish = self
99                        .buffered_deltas_map
100                        .remove(&instrument_id)
101                        .expect("buffered deltas exist");
102                    let topic = switchboard::get_book_deltas_topic(instrument_id);
103                    msgbus::publish_deltas(topic, &deltas_to_publish);
104                    self.reclaim_deltas_frame(mem::take(&mut deltas_to_publish.deltas));
105                }
106            }
107        } else {
108            let topic = switchboard::get_book_deltas_topic(deltas.instrument_id);
109            msgbus::publish_deltas(topic, deltas);
110        }
111    }
112
113    pub(super) fn handle_depth(&self, depth: &OrderBookDepth) {
114        let topic = switchboard::get_book_depth_topic(depth.instrument_id);
115        msgbus::publish_depth(topic, depth);
116
117        if self.config.emit_quotes_from_book_depths
118            && let Some(quote) = derive_quote_from_depth(depth)
119        {
120            book::publish_quote_if_changed(&self.cache, quote);
121        }
122    }
123
124    pub(super) fn handle_quote(&self, quote: QuoteTick) {
125        if let Err(e) = self.cache.as_ref().borrow_mut().add_quote(quote) {
126            log_error_on_cache_insert(&e);
127        }
128
129        for synthetic_quote in self.synthetic_quotes_from_quote(quote) {
130            let topic = switchboard::get_quotes_topic(synthetic_quote.instrument_id);
131            msgbus::publish_quote(topic, &synthetic_quote);
132        }
133
134        let topic = switchboard::get_quotes_topic(quote.instrument_id);
135        msgbus::publish_quote(topic, &quote);
136    }
137
138    pub(super) fn handle_trade(&self, trade: TradeTick) {
139        if let Err(e) = self.cache.as_ref().borrow_mut().add_trade(trade) {
140            log_error_on_cache_insert(&e);
141        }
142
143        for synthetic_trade in self.synthetic_trades_from_trade(trade) {
144            let topic = switchboard::get_trades_topic(synthetic_trade.instrument_id);
145            msgbus::publish_trade(topic, &synthetic_trade);
146        }
147
148        let topic = switchboard::get_trades_topic(trade.instrument_id);
149        msgbus::publish_trade(topic, &trade);
150    }
151
152    pub(super) fn handle_bar(&self, bar: Bar) {
153        process_engine_bar(&self.cache, self.config.validate_data_sequence, true, bar);
154    }
155
156    pub(super) fn handle_mark_price(&self, mark_price: MarkPriceUpdate) {
157        if let Err(e) = self.cache.as_ref().borrow_mut().add_mark_price(mark_price) {
158            log_error_on_cache_insert(&e);
159        }
160
161        let topic = switchboard::get_mark_price_topic(mark_price.instrument_id);
162        msgbus::publish_mark_price(topic, &mark_price);
163    }
164
165    pub(super) fn handle_index_price(&self, index_price: IndexPriceUpdate) {
166        if let Err(e) = self
167            .cache
168            .as_ref()
169            .borrow_mut()
170            .add_index_price(index_price)
171        {
172            log_error_on_cache_insert(&e);
173        }
174
175        let topic = switchboard::get_index_price_topic(index_price.instrument_id);
176        msgbus::publish_index_price(topic, &index_price);
177    }
178
179    /// Handles a funding rate update by adding it to the cache and publishing to the message bus.
180    pub fn handle_funding_rate(&mut self, funding_rate: FundingRateUpdate) {
181        if let Err(e) = self
182            .cache
183            .as_ref()
184            .borrow_mut()
185            .add_funding_rate(funding_rate)
186        {
187            log_error_on_cache_insert(&e);
188        }
189
190        let topic = switchboard::get_funding_rate_topic(funding_rate.instrument_id);
191        msgbus::publish_funding_rate(topic, &funding_rate);
192    }
193
194    pub(super) fn handle_instrument_status(&mut self, status: InstrumentStatus) {
195        if let Err(e) = self
196            .cache
197            .as_ref()
198            .borrow_mut()
199            .add_instrument_status(status)
200        {
201            log_error_on_cache_insert(&e);
202        }
203
204        let topic = switchboard::get_instrument_status_topic(status.instrument_id);
205        msgbus::publish_any(topic, &status);
206
207        if self
208            .option_chain_instrument_index
209            .contains_key(&status.instrument_id)
210            && matches!(
211                status.action,
212                MarketStatusAction::Close | MarketStatusAction::NotAvailableForTrading
213            )
214        {
215            self.expire_option_chain_instrument(status.instrument_id);
216        }
217    }
218
219    pub(super) fn handle_instrument_close(&self, close: InstrumentClose) {
220        let topic = switchboard::get_instrument_close_topic(close.instrument_id);
221        msgbus::publish_any(topic, &close);
222    }
223
224    pub(super) fn handle_custom_data(&self, custom: &CustomData) {
225        log::debug!("Processing custom data: {}", custom.data.type_name());
226        self.cache.borrow_mut().add_custom_data(custom.clone());
227        let topic = switchboard::get_custom_topic(&custom.data_type);
228        msgbus::publish_any(topic, custom);
229    }
230
231    pub(super) fn handle_delta_pipeline(&mut self, delta: OrderBookDelta) {
232        // Pipeline deltas are not buffered; replays arrive pre-batched
233        let mut deltas = self.single_delta_batch(delta);
234        let topic = switchboard::get_pipeline_book_deltas_topic(deltas.instrument_id);
235        msgbus::publish_deltas(topic, &deltas);
236        self.reclaim_deltas_frame(mem::take(&mut deltas.deltas));
237    }
238
239    fn buffer_delta(&mut self, delta: OrderBookDelta) {
240        if let Some(buffered_deltas) = self.buffered_deltas_map.get_mut(&delta.instrument_id) {
241            buffered_deltas.deltas.push(delta);
242            buffered_deltas.flags = delta.flags;
243            buffered_deltas.sequence = delta.sequence;
244            buffered_deltas.ts_event = delta.ts_event;
245            buffered_deltas.ts_init = delta.ts_init;
246            return;
247        }
248
249        let instrument_id = delta.instrument_id;
250        let buffered_deltas = self.single_delta_batch(delta);
251        self.buffered_deltas_map
252            .insert(instrument_id, buffered_deltas);
253    }
254
255    fn single_delta_batch(&mut self, delta: OrderBookDelta) -> OrderBookDeltas {
256        let instrument_id = delta.instrument_id;
257        let mut frame = mem::take(&mut self.deltas_frame);
258        frame.clear();
259        frame.push(delta);
260        OrderBookDeltas::new(instrument_id, frame)
261    }
262
263    fn reclaim_deltas_frame(&mut self, mut frame: Vec<OrderBookDelta>) {
264        frame.clear();
265        self.deltas_frame = frame;
266    }
267
268    pub(super) fn handle_deltas_pipeline(&self, deltas: &OrderBookDeltas) {
269        let topic = switchboard::get_pipeline_book_deltas_topic(deltas.instrument_id);
270        msgbus::publish_deltas(topic, deltas);
271    }
272
273    pub(super) fn handle_depth_pipeline(&self, depth: &OrderBookDepth) {
274        let topic = switchboard::get_pipeline_book_depth_topic(depth.instrument_id);
275        msgbus::publish_depth(topic, depth);
276    }
277
278    pub(super) fn handle_quote_pipeline(&self, quote: QuoteTick) {
279        if self.pipeline_cache_writes_allowed()
280            && let Err(e) = self.cache.as_ref().borrow_mut().add_quote(quote)
281        {
282            log_error_on_cache_insert(&e);
283        }
284
285        let topic = switchboard::get_pipeline_quotes_topic(quote.instrument_id);
286        msgbus::publish_quote(topic, &quote);
287    }
288
289    pub(super) fn handle_trade_pipeline(&self, trade: TradeTick) {
290        if self.pipeline_cache_writes_allowed()
291            && let Err(e) = self.cache.as_ref().borrow_mut().add_trade(trade)
292        {
293            log_error_on_cache_insert(&e);
294        }
295
296        let topic = switchboard::get_pipeline_trades_topic(trade.instrument_id);
297        msgbus::publish_trade(topic, &trade);
298    }
299
300    pub(super) fn handle_bar_pipeline(&self, bar: Bar) {
301        if !validate_bar_sequence(&self.cache, self.config.validate_data_sequence, &bar) {
302            return;
303        }
304
305        if self.pipeline_cache_writes_allowed()
306            && let Err(e) = self.cache.as_ref().borrow_mut().add_bar(bar)
307        {
308            log_error_on_cache_insert(&e);
309        }
310
311        let topic = switchboard::get_pipeline_bars_topic(bar.bar_type);
312        msgbus::publish_bar(topic, &bar);
313    }
314
315    pub(super) fn handle_mark_price_pipeline(&self, mark_price: MarkPriceUpdate) {
316        if self.pipeline_cache_writes_allowed()
317            && let Err(e) = self.cache.as_ref().borrow_mut().add_mark_price(mark_price)
318        {
319            log_error_on_cache_insert(&e);
320        }
321
322        let topic = switchboard::get_pipeline_mark_price_topic(mark_price.instrument_id);
323        msgbus::publish_mark_price(topic, &mark_price);
324    }
325
326    pub(super) fn handle_index_price_pipeline(&self, index_price: IndexPriceUpdate) {
327        if self.pipeline_cache_writes_allowed()
328            && let Err(e) = self
329                .cache
330                .as_ref()
331                .borrow_mut()
332                .add_index_price(index_price)
333        {
334            log_error_on_cache_insert(&e);
335        }
336
337        let topic = switchboard::get_pipeline_index_price_topic(index_price.instrument_id);
338        msgbus::publish_index_price(topic, &index_price);
339    }
340
341    pub(super) fn handle_funding_rate_pipeline(&self, funding_rate: FundingRateUpdate) {
342        if self.pipeline_cache_writes_allowed()
343            && let Err(e) = self
344                .cache
345                .as_ref()
346                .borrow_mut()
347                .add_funding_rate(funding_rate)
348        {
349            log_error_on_cache_insert(&e);
350        }
351
352        let topic = switchboard::get_pipeline_funding_rate_topic(funding_rate.instrument_id);
353        msgbus::publish_funding_rate(topic, &funding_rate);
354    }
355
356    pub(super) fn handle_instrument_status_pipeline(&self, status: InstrumentStatus) {
357        if self.pipeline_cache_writes_allowed()
358            && let Err(e) = self
359                .cache
360                .as_ref()
361                .borrow_mut()
362                .add_instrument_status(status)
363        {
364            log_error_on_cache_insert(&e);
365        }
366
367        let topic = switchboard::get_pipeline_instrument_status_topic(status.instrument_id);
368        msgbus::publish_any(topic, &status);
369    }
370
371    pub(super) fn handle_option_greeks_pipeline(&self, greeks: OptionGreeks) {
372        if self.pipeline_cache_writes_allowed() {
373            self.cache.borrow_mut().add_option_greeks(greeks);
374        }
375
376        let topic = switchboard::get_pipeline_option_greeks_topic(greeks.instrument_id);
377        msgbus::publish_option_greeks(topic, &greeks);
378    }
379
380    pub(super) fn handle_instrument_close_pipeline(&self, close: InstrumentClose) {
381        let topic = switchboard::get_pipeline_instrument_close_topic(close.instrument_id);
382        msgbus::publish_any(topic, &close);
383    }
384
385    pub(super) fn handle_custom_data_pipeline(&self, custom: &CustomData) {
386        log::debug!("Pipeline custom data: {}", custom.data.type_name());
387
388        if self.pipeline_cache_writes_allowed() {
389            self.cache.borrow_mut().add_custom_data(custom.clone());
390        }
391
392        let topic = switchboard::get_pipeline_custom_topic(&custom.data_type);
393        msgbus::publish_any(topic, custom);
394    }
395
396    pub(super) fn handle_quotes(&self, quotes: &[QuoteTick]) {
397        if let Err(e) = self.cache.as_ref().borrow_mut().add_quotes(quotes) {
398            log_error_on_cache_insert(&e);
399        }
400    }
401
402    pub(super) fn handle_trades(&self, trades: &[TradeTick]) {
403        if let Err(e) = self.cache.as_ref().borrow_mut().add_trades(trades) {
404            log_error_on_cache_insert(&e);
405        }
406    }
407
408    pub(super) fn handle_funding_rates(&self, funding_rates: &[FundingRateUpdate]) {
409        if let Err(e) = self
410            .cache
411            .as_ref()
412            .borrow_mut()
413            .add_funding_rates(funding_rates)
414        {
415            log_error_on_cache_insert(&e);
416        }
417    }
418
419    pub(super) fn handle_bars(&self, bars: &[Bar]) {
420        if let Err(e) = self.cache.as_ref().borrow_mut().add_bars(bars) {
421            log_error_on_cache_insert(&e);
422        }
423    }
424}
425
426#[inline(always)]
427pub(super) fn log_error_on_cache_insert<T: Display>(e: &T) {
428    log::error!("Error on cache insert: {e}");
429}
430
431// Top-of-book `QuoteTick` from an `OrderBookDepth`. Returns `None` for
432// missing-side padding or zero size.
433fn derive_quote_from_depth(depth: &OrderBookDepth) -> Option<QuoteTick> {
434    let bid = depth.bids.first()?;
435    let ask = depth.asks.first()?;
436
437    if bid.side.is_none() || ask.side.is_none() || bid.size.is_zero() || ask.size.is_zero() {
438        return None;
439    }
440
441    Some(QuoteTick::new(
442        depth.instrument_id,
443        bid.price,
444        ask.price,
445        bid.size,
446        ask.size,
447        depth.ts_event,
448        depth.ts_init,
449    ))
450}
451
452// Validates a bar against `last_bar` before writing and (optionally) publishing.
453// Live bars and aggregator emissions honor `validate_data_sequence`;
454// request-generated bars use `Cache::add_bar_historical`.
455pub(super) fn process_engine_bar(
456    cache: &Rc<RefCell<Cache>>,
457    validate_sequence: bool,
458    publish: bool,
459    bar: Bar,
460) {
461    debug_assert!(
462        bar.bar_type.is_standard(),
463        "bars must be published and cached under the standard bar type"
464    );
465
466    if !validate_bar_sequence(cache, validate_sequence, &bar) {
467        return;
468    }
469
470    if let Err(e) = cache.as_ref().borrow_mut().add_bar(bar) {
471        log_error_on_cache_insert(&e);
472    }
473
474    if publish {
475        let topic = switchboard::get_bars_topic(bar.bar_type);
476        msgbus::publish_bar(topic, &bar);
477    }
478}
479
480fn validate_bar_sequence(cache: &Rc<RefCell<Cache>>, validate_sequence: bool, bar: &Bar) -> bool {
481    if !validate_sequence {
482        return true;
483    }
484
485    let Some(last_bar) = cache.as_ref().borrow().bar(&bar.bar_type).copied() else {
486        return true;
487    };
488
489    if bar.ts_event < last_bar.ts_event {
490        log::warn!(
491            "Bar {bar} was prior to last bar `ts_event` {}",
492            last_bar.ts_event,
493        );
494        return false;
495    }
496
497    if bar.ts_init < last_bar.ts_init {
498        log::warn!(
499            "Bar {bar} was prior to last bar `ts_init` {}",
500            last_bar.ts_init,
501        );
502        return false;
503    }
504
505    true
506}