Skip to main content

nautilus_common/msgbus/
mod.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//! In-memory message bus for intra-process communication.
17//!
18//! # Messaging patterns
19//!
20//! - **Point-to-point**: Send messages to named endpoints via `send_*` functions.
21//! - **Pub/sub**: Publish messages to topics via `publish_*`, subscribers receive
22//!   all messages matching their pattern.
23//! - **Request/response**: Register correlation IDs for response sequence tracking.
24//!
25//! # Architecture
26//!
27//! The bus uses thread-local storage for single-threaded async runtimes. Each
28//! thread gets its own `MessageBus` instance, avoiding synchronization overhead.
29//!
30//! Two routing mechanisms serve different needs:
31//!
32//! - **Typed routing** (`publish_quote`, `subscribe_quotes`): Zero-cost dispatch
33//!   for known types. Handlers receive `&T` directly with no runtime type checking.
34//! - **Any-based routing** (`publish_any`, `subscribe_any`): Flexible dispatch for
35//!   custom types and Python interop. Handlers receive `&dyn Any`.
36//!
37//! See [`core`] module documentation for design decisions and performance details.
38
39pub mod config;
40pub mod core;
41pub mod matching;
42pub mod message;
43pub mod mstr;
44pub mod stubs;
45pub mod switchboard;
46pub mod typed_endpoints;
47pub mod typed_handler;
48pub mod typed_router;
49
50pub(crate) mod external;
51
52mod api;
53mod backing;
54
55use std::{
56    any::Any,
57    cell::{Cell, RefCell},
58    rc::Rc,
59};
60
61use nautilus_core::UUID4;
62#[cfg(feature = "defi")]
63use nautilus_model::defi::{Block, Pool, PoolFeeCollect, PoolFlash, PoolLiquidityUpdate, PoolSwap};
64use nautilus_model::{
65    data::{
66        Bar, FundingRateUpdate, GreeksData, IndexPriceUpdate, MarkPriceUpdate, OrderBookDeltas,
67        OrderBookDepth, QuoteTick, TradeTick,
68        option_chain::{OptionChainSlice, OptionGreeks},
69    },
70    events::{AccountState, OrderEventAny, PortfolioSnapshot, PositionEvent},
71    instruments::InstrumentAny,
72    orderbook::OrderBook,
73};
74use smallvec::SmallVec;
75
76#[cfg(feature = "live")]
77pub use self::backing::{
78    MessageBusExternalIngress, MessageBusExternalReceiver, external_io_from_backing,
79};
80pub use self::{
81    api::*,
82    backing::{
83        MessageBusBacking, MessageBusBackingFactory, MessageBusExternalEgress,
84        external_egress_from_backing,
85    },
86    config::MessageBusConfig,
87    core::{MessageBus, Subscription},
88    external::{current_external_source, republish_pending_external_response},
89    message::{BusMessage, BusMessageSource, BusPayloadCategory, BusPayloadType},
90    mstr::{Endpoint, MStr, Pattern, Topic},
91    switchboard::MessagingSwitchboard,
92    typed_endpoints::{EndpointMap, IntoEndpointMap},
93    typed_handler::{
94        CallbackHandler, Handler, IntoHandler, ShareableMessageHandler, TypedHandler,
95        TypedIntoHandler,
96    },
97    typed_router::{TopicRouter, TypedSubscription},
98};
99use crate::timer::TimeEvent;
100
101/// Inline capacity for handler buffers before heap allocation.
102pub(super) const HANDLER_BUFFER_CAP: usize = 64;
103
104// MessageBus is designed for single-threaded use within each async runtime.
105// Thread-local storage ensures each thread gets its own instance, eliminating
106// the need for unsafe Send/Sync implementations.
107//
108// Handler buffers provide zero-allocation publish on hot paths.
109// Each buffer stores up to 64 handlers inline before spilling to heap.
110// Publish functions use move-out/move-back to avoid holding RefCell borrows
111// during handler calls (enabling re-entrant publishes).
112thread_local! {
113    pub(super) static MESSAGE_BUS: RefCell<Option<Rc<RefCell<MessageBus>>>> = const { RefCell::new(None) };
114    pub(super) static HAS_EXTERNAL_EGRESS: Cell<bool> = const { Cell::new(false) };
115    pub(super) static HAS_EXTERNAL_DATA_INGRESS: Cell<bool> = const { Cell::new(false) };
116    pub(super) static SUPPRESS_EXTERNAL_DEPTH: Cell<u32> = const { Cell::new(0) };
117
118    pub(super) static ANY_HANDLERS: RefCell<SmallVec<[ShareableMessageHandler; HANDLER_BUFFER_CAP]>> =
119        RefCell::new(SmallVec::new());
120
121    pub(super) static DELTAS_HANDLERS: RefCell<SmallVec<[TypedHandler<OrderBookDeltas>; HANDLER_BUFFER_CAP]>> =
122        RefCell::new(SmallVec::new());
123    pub(super) static DEPTH_HANDLERS: RefCell<SmallVec<[TypedHandler<OrderBookDepth>; HANDLER_BUFFER_CAP]>> =
124        RefCell::new(SmallVec::new());
125    pub(super) static BOOK_HANDLERS: RefCell<SmallVec<[TypedHandler<OrderBook>; HANDLER_BUFFER_CAP]>> =
126        RefCell::new(SmallVec::new());
127    pub(super) static QUOTE_HANDLERS: RefCell<SmallVec<[TypedHandler<QuoteTick>; HANDLER_BUFFER_CAP]>> =
128        RefCell::new(SmallVec::new());
129    pub(super) static TRADE_HANDLERS: RefCell<SmallVec<[TypedHandler<TradeTick>; HANDLER_BUFFER_CAP]>> =
130        RefCell::new(SmallVec::new());
131    pub(super) static BAR_HANDLERS: RefCell<SmallVec<[TypedHandler<Bar>; HANDLER_BUFFER_CAP]>> =
132        RefCell::new(SmallVec::new());
133    pub(super) static MARK_PRICE_HANDLERS: RefCell<SmallVec<[TypedHandler<MarkPriceUpdate>; HANDLER_BUFFER_CAP]>> =
134        RefCell::new(SmallVec::new());
135    pub(super) static INDEX_PRICE_HANDLERS: RefCell<SmallVec<[TypedHandler<IndexPriceUpdate>; HANDLER_BUFFER_CAP]>> =
136        RefCell::new(SmallVec::new());
137    pub(super) static FUNDING_RATE_HANDLERS: RefCell<SmallVec<[TypedHandler<FundingRateUpdate>; HANDLER_BUFFER_CAP]>> =
138        RefCell::new(SmallVec::new());
139    pub(super) static GREEKS_HANDLERS: RefCell<SmallVec<[TypedHandler<GreeksData>; HANDLER_BUFFER_CAP]>> =
140        RefCell::new(SmallVec::new());
141    pub(super) static OPTION_GREEKS_HANDLERS: RefCell<SmallVec<[TypedHandler<OptionGreeks>; HANDLER_BUFFER_CAP]>> =
142        RefCell::new(SmallVec::new());
143    pub(super) static OPTION_CHAIN_HANDLERS: RefCell<SmallVec<[TypedHandler<OptionChainSlice>; HANDLER_BUFFER_CAP]>> =
144        RefCell::new(SmallVec::new());
145    pub(super) static ACCOUNT_STATE_HANDLERS: RefCell<SmallVec<[TypedHandler<AccountState>; HANDLER_BUFFER_CAP]>> =
146        RefCell::new(SmallVec::new());
147    pub(super) static PORTFOLIO_SNAPSHOT_HANDLERS: RefCell<SmallVec<[TypedHandler<PortfolioSnapshot>; HANDLER_BUFFER_CAP]>> =
148        RefCell::new(SmallVec::new());
149    pub(super) static ORDER_EVENT_HANDLERS: RefCell<SmallVec<[TypedHandler<OrderEventAny>; HANDLER_BUFFER_CAP]>> =
150        RefCell::new(SmallVec::new());
151    pub(super) static POSITION_EVENT_HANDLERS: RefCell<SmallVec<[TypedHandler<PositionEvent>; HANDLER_BUFFER_CAP]>> =
152        RefCell::new(SmallVec::new());
153    pub(super) static INSTRUMENT_HANDLERS: RefCell<SmallVec<[TypedHandler<InstrumentAny>; HANDLER_BUFFER_CAP]>> =
154        RefCell::new(SmallVec::new());
155
156    #[cfg(feature = "defi")]
157    pub(super) static DEFI_BLOCK_HANDLERS: RefCell<SmallVec<[TypedHandler<Block>; HANDLER_BUFFER_CAP]>> =
158        RefCell::new(SmallVec::new());
159    #[cfg(feature = "defi")]
160    pub(super) static DEFI_POOL_HANDLERS: RefCell<SmallVec<[TypedHandler<Pool>; HANDLER_BUFFER_CAP]>> =
161        RefCell::new(SmallVec::new());
162    #[cfg(feature = "defi")]
163    pub(super) static DEFI_SWAP_HANDLERS: RefCell<SmallVec<[TypedHandler<PoolSwap>; HANDLER_BUFFER_CAP]>> =
164        RefCell::new(SmallVec::new());
165    #[cfg(feature = "defi")]
166    pub(super) static DEFI_LIQUIDITY_HANDLERS: RefCell<SmallVec<[TypedHandler<PoolLiquidityUpdate>; HANDLER_BUFFER_CAP]>> =
167        RefCell::new(SmallVec::new());
168    #[cfg(feature = "defi")]
169    pub(super) static DEFI_COLLECT_HANDLERS: RefCell<SmallVec<[TypedHandler<PoolFeeCollect>; HANDLER_BUFFER_CAP]>> =
170        RefCell::new(SmallVec::new());
171    #[cfg(feature = "defi")]
172    pub(super) static DEFI_FLASH_HANDLERS: RefCell<SmallVec<[TypedHandler<PoolFlash>; HANDLER_BUFFER_CAP]>> =
173        RefCell::new(SmallVec::new());
174}
175
176/// Guard that prevents republished external messages from being forwarded again.
177#[derive(Debug)]
178pub struct SuppressExternalGuard;
179
180impl SuppressExternalGuard {
181    #[must_use]
182    pub fn new() -> Self {
183        SUPPRESS_EXTERNAL_DEPTH.with(|depth| depth.set(depth.get().saturating_add(1)));
184        Self
185    }
186}
187
188impl Default for SuppressExternalGuard {
189    fn default() -> Self {
190        Self::new()
191    }
192}
193
194impl Drop for SuppressExternalGuard {
195    fn drop(&mut self) {
196        SUPPRESS_EXTERNAL_DEPTH.with(|depth| depth.set(depth.get().saturating_sub(1)));
197    }
198}
199
200/// Sets the thread-local message bus, replacing any existing one.
201pub fn set_message_bus(msgbus: Rc<RefCell<MessageBus>>) {
202    HAS_EXTERNAL_EGRESS.with(|flag| flag.set(msgbus.borrow().has_external_egress()));
203    HAS_EXTERNAL_DATA_INGRESS.with(|flag| flag.set(msgbus.borrow().has_external_data_ingress()));
204    MESSAGE_BUS.with(|bus| {
205        *bus.borrow_mut() = Some(msgbus);
206    });
207}
208
209/// Gets the thread-local message bus.
210///
211/// If no message bus has been set for this thread, a default one is created and initialized.
212pub fn get_message_bus() -> Rc<RefCell<MessageBus>> {
213    MESSAGE_BUS.with(|bus| {
214        let mut slot = bus.borrow_mut();
215        let rc = slot.get_or_insert_with(|| Rc::new(RefCell::new(MessageBus::default())));
216        rc.clone()
217    })
218}
219
220/// Returns the thread-local message bus if one has been set for this thread.
221pub fn try_get_message_bus() -> Option<Rc<RefCell<MessageBus>>> {
222    MESSAGE_BUS.with(|bus| bus.borrow().clone())
223}
224
225/// Observes dispatched bus traffic for the durable event store.
226///
227/// The bus invokes the registered tap (when present) before each publish, send, or
228/// correlation response fanout, so subscribers cannot observe a message that has not
229/// yet been handed to the tap. The tap callback runs on the engine thread and must be
230/// cheap; it must not re-enter the bus (the bus is single-threaded and the call site
231/// holds no live borrow of the bus, so any re-entrant publish would deadlock through
232/// downstream `RefCell::borrow_mut` calls inside the registered tap).
233pub trait BusTap: 'static {
234    /// Invoked before a publish fanout dispatches to subscribers on `topic`.
235    fn on_publish(&self, topic: MStr<Topic>, message: &dyn Any);
236
237    /// Invoked before a send dispatch reaches the endpoint handler.
238    fn on_send(&self, endpoint: MStr<Endpoint>, message: &dyn Any);
239
240    /// Invoked before a correlation response dispatch reaches the response handler.
241    fn on_response(&self, _correlation_id: &UUID4, _message: &dyn Any) {}
242}
243
244thread_local! {
245    pub(super) static BUS_TAP: RefCell<Option<Rc<dyn BusTap>>> = const { RefCell::new(None) };
246}
247
248/// Registers `tap` as the thread-local bus tap, replacing any previously installed tap.
249///
250/// The tap fires before each publish, send, and correlation response fanout. Callers
251/// are responsible for clearing the tap on shutdown via [`clear_bus_tap`] so a stale
252/// adapter does not outlive the writer it captures into.
253pub fn set_bus_tap(tap: Rc<dyn BusTap>) {
254    BUS_TAP.with(|slot| {
255        *slot.borrow_mut() = Some(tap);
256    });
257}
258
259/// Clears the registered bus tap on this thread.
260///
261/// A no-op when no tap is installed.
262pub fn clear_bus_tap() {
263    BUS_TAP.with(|slot| {
264        *slot.borrow_mut() = None;
265    });
266}
267
268#[inline]
269pub(super) fn dispatch_tap_publish(topic: MStr<Topic>, message: &dyn Any) {
270    // Clone the Rc so the cell borrow is released before the tap runs. The tap is
271    // single-threaded with the bus; a re-entrant `set_bus_tap` during dispatch would
272    // otherwise panic on RefCell.
273    let tap = BUS_TAP.with(|slot| slot.borrow().clone());
274    if let Some(tap) = tap {
275        tap.on_publish(topic, message);
276    }
277}
278
279#[inline]
280pub(super) fn dispatch_tap_send(endpoint: MStr<Endpoint>, message: &dyn Any) {
281    let tap = BUS_TAP.with(|slot| slot.borrow().clone());
282    if let Some(tap) = tap {
283        tap.on_send(endpoint, message);
284    }
285}
286
287#[inline]
288pub(super) fn dispatch_tap_response(correlation_id: &UUID4, message: &dyn Any) {
289    let tap = BUS_TAP.with(|slot| slot.borrow().clone());
290    if let Some(tap) = tap {
291        tap.on_response(correlation_id, message);
292    }
293}
294
295#[inline]
296pub(crate) fn dispatch_tap_time_event(event: &TimeEvent) {
297    dispatch_tap_publish(MessagingSwitchboard::time_event_topic(), event);
298}