Skip to main content

nautilus_common/msgbus/
core.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//! Core message bus implementation.
17//!
18//! # Design decisions
19//!
20//! ## Why two routing mechanisms?
21//!
22//! The message bus provides typed and Any-based routing to balance performance
23//! and flexibility:
24//!
25//! **Typed routing** optimizes for throughput on known data types:
26//! - `TopicRouter<T>` for pub/sub, `EndpointMap<T>` for point-to-point.
27//! - Handlers implement `Handler<T>`, receive `&T` directly.
28//! - No runtime type checking enables inlining and static dispatch.
29//! - Built-in routers: `QuoteTick`, `TradeTick`, `Bar`, `OrderBookDeltas`,
30//!   `OrderBookDepth`, `OrderEventAny`, `PositionEvent`, `AccountState`.
31//!
32//! **Any-based routing** provides flexibility for extensibility:
33//! - `subscriptions`/`topics` maps with `ShareableMessageHandler`.
34//! - Handlers implement `Handler<dyn Any>`, receive `&dyn Any`.
35//! - Supports arbitrary message types without modifying the bus.
36//! - Required for Python interop where types aren't known at compile time.
37//!
38//! ## Handler semantics
39//!
40//! **Typed handlers receive `&T` references:**
41//! - Same message delivered to N handlers without cloning.
42//! - Handler decides whether to clone (only if storing).
43//! - Zero-cost for `Copy` types (`QuoteTick`, `TradeTick`, `Bar`).
44//! - Efficient for large types (`OrderBookDeltas`).
45//!
46//! **Any-based handlers pay per-handler overhead:**
47//! - Each handler receives `&dyn Any`, must downcast to `&T`.
48//! - N handlers = N downcasts + N potential clones.
49//! - Runtime type checking on every dispatch.
50//!
51//! ## Performance trade-off
52//!
53//! Typed routing is faster (see `benches/msgbus_typed.rs`, AMD Ryzen 9 7950X):
54//!
55//! | Scenario                    | Typed vs Any |
56//! |-----------------------------|--------------|
57//! | Handler dispatch (noop)     | ~10x faster  |
58//! | Router with 5 subscribers   | ~3.5x faster |
59//! | Router with 10 subscribers  | ~2x faster   |
60//! | High volume (1M messages)   | ~7% faster   |
61//!
62//! Any-based routing pays for flexibility with runtime type checking. Use
63//! typed routing for hot-path data; Any-based for custom types and Python.
64//!
65//! ## Routing paths are separate
66//!
67//! Typed and Any-based routing use separate data structures:
68//! - `publish_quote` routes through `router_quotes`.
69//! - `publish_any` routes through `topics`.
70//!
71//! Publishers and subscribers must use matching APIs. Mixing them causes
72//! silent message loss.
73//!
74//! ## When to use each
75//!
76//! **Typed** (`publish_quote`, `subscribe_quotes`, etc.):
77//! - Market data (quotes, trades, bars, order book updates).
78//! - Order and position events.
79//! - High-frequency data with known types.
80//!
81//! **Any-based** (`publish_any`, `subscribe_any`):
82//! - Custom or user-defined data types.
83//! - Low-frequency messages.
84//! - Python callbacks.
85
86use std::{
87    any::{Any, TypeId},
88    cell::RefCell,
89    collections::HashMap,
90    fmt::Debug,
91    hash::{Hash, Hasher},
92    ptr::eq,
93    rc::Rc,
94};
95
96use ahash::{AHashMap, AHashSet};
97use indexmap::IndexMap;
98use nautilus_core::UUID4;
99use nautilus_model::{
100    data::{
101        Bar, Data, FundingRateUpdate, GreeksData, IndexPriceUpdate, MarkPriceUpdate,
102        OrderBookDeltas, OrderBookDepth, QuoteTick, TradeTick,
103        option_chain::{OptionChainSlice, OptionGreeks},
104    },
105    events::{AccountState, OrderEventAny, PortfolioSnapshot, PositionEvent},
106    identifiers::TraderId,
107    instruments::InstrumentAny,
108    orderbook::OrderBook,
109    orders::OrderAny,
110    position::Position,
111};
112use smallvec::SmallVec;
113use ustr::Ustr;
114
115use super::{
116    HAS_EXTERNAL_DATA_INGRESS, HAS_EXTERNAL_EGRESS, ShareableMessageHandler, TypedHandler,
117    backing::MessageBusExternalEgress,
118    config::MessageBusConfig,
119    matching::is_matching_backtracking,
120    message::{BusPayloadCategory, BusPayloadType},
121    mstr::{Endpoint, MStr, Pattern, Topic},
122    set_message_bus,
123    switchboard::MessagingSwitchboard,
124    try_get_message_bus,
125    typed_endpoints::{EndpointMap, IntoEndpointMap},
126    typed_router::TopicRouter,
127};
128use crate::{
129    enums::SerializationEncoding,
130    messages::{
131        data::{DataCommand, DataResponse, DataResponseEnvelope},
132        execution::{ExecutionReport, TradingCommand},
133    },
134};
135
136/// Represents a subscription to a particular topic.
137///
138/// This is an internal class intended to be used by the message bus to organize
139/// topics and their subscribers.
140#[derive(Clone, Debug)]
141pub struct Subscription {
142    /// The shareable message handler for the subscription.
143    pub handler: ShareableMessageHandler,
144    /// Store a copy of the handler ID for faster equality checks.
145    pub handler_id: Ustr,
146    /// The pattern for the subscription.
147    pub pattern: MStr<Pattern>,
148    /// The priority for the subscription determines the ordering of handlers receiving
149    /// messages being processed, higher priority handlers will receive messages before
150    /// lower priority handlers.
151    pub priority: u32,
152}
153
154impl Subscription {
155    /// Creates a new [`Subscription`] instance.
156    #[must_use]
157    pub fn new(
158        pattern: MStr<Pattern>,
159        handler: ShareableMessageHandler,
160        priority: Option<u32>,
161    ) -> Self {
162        Self {
163            handler_id: handler.0.id(),
164            pattern,
165            handler,
166            priority: priority.unwrap_or(0),
167        }
168    }
169
170    pub(crate) fn delivery_order(&self, other: &Self) -> std::cmp::Ordering {
171        other
172            .priority
173            .cmp(&self.priority)
174            .then_with(|| self.pattern.cmp(&other.pattern))
175            .then_with(|| self.handler_id.cmp(&other.handler_id))
176    }
177}
178
179impl PartialEq<Self> for Subscription {
180    fn eq(&self, other: &Self) -> bool {
181        self.pattern == other.pattern && self.handler_id == other.handler_id
182    }
183}
184
185impl Eq for Subscription {}
186
187impl PartialOrd for Subscription {
188    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
189        Some(self.cmp(other))
190    }
191}
192
193impl Ord for Subscription {
194    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
195        self.pattern
196            .cmp(&other.pattern)
197            .then_with(|| self.handler_id.cmp(&other.handler_id))
198    }
199}
200
201impl Hash for Subscription {
202    fn hash<H: Hasher>(&self, state: &mut H) {
203        self.pattern.hash(state);
204        self.handler_id.hash(state);
205    }
206}
207
208/// A generic message bus to facilitate various messaging patterns.
209///
210/// The bus provides both a producer and consumer API for Pub/Sub, Req/Rep, as
211/// well as direct point-to-point messaging to registered endpoints.
212///
213/// Pub/Sub wildcard patterns for hierarchical topics are possible:
214///  - `*` asterisk represents one or more characters in a pattern.
215///  - `?` question mark represents a single character in a pattern.
216///
217/// Given a topic and pattern potentially containing wildcard characters, i.e.
218/// `*` and `?`, where `?` can match any single character in the topic, and `*`
219/// can match any number of characters including zero characters.
220///
221/// The asterisk in a wildcard matches any character zero or more times. For
222/// example, `comp*` matches anything beginning with `comp` which means `comp`,
223/// `complete`, and `computer` are all matched.
224///
225/// A question mark matches a single character once. For example, `c?mp` matches
226/// `camp` and `comp`. The question mark can also be used more than once.
227/// For example, `c??p` would match both of the above examples and `coop`.
228pub struct MessageBus {
229    /// The trader ID associated with the message bus.
230    pub trader_id: TraderId,
231    /// The instance ID associated with the message bus.
232    pub instance_id: UUID4,
233    /// The name for the message bus.
234    pub name: String,
235    /// If the message bus is backed by a database.
236    pub has_backing: bool,
237    pub(crate) switchboard: MessagingSwitchboard,
238    pub(crate) subscriptions: AHashSet<Subscription>,
239    pub(crate) topics: IndexMap<MStr<Topic>, Vec<Subscription>>,
240    pub(crate) endpoints: IndexMap<MStr<Endpoint>, ShareableMessageHandler>,
241    pub(crate) correlation_index: AHashMap<UUID4, TypedHandler<DataResponseEnvelope>>,
242    pub(crate) router_quotes: TopicRouter<QuoteTick>,
243    pub(crate) router_trades: TopicRouter<TradeTick>,
244    pub(crate) router_bars: TopicRouter<Bar>,
245    pub(crate) router_deltas: TopicRouter<OrderBookDeltas>,
246    pub(crate) router_depth: TopicRouter<OrderBookDepth>,
247    pub(crate) router_book_snapshots: TopicRouter<OrderBook>,
248    pub(crate) router_mark_prices: TopicRouter<MarkPriceUpdate>,
249    pub(crate) router_index_prices: TopicRouter<IndexPriceUpdate>,
250    pub(crate) router_funding_rates: TopicRouter<FundingRateUpdate>,
251    pub(crate) router_order_events: TopicRouter<OrderEventAny>,
252    pub(crate) router_position_events: TopicRouter<PositionEvent>,
253    pub(crate) router_account_state: TopicRouter<AccountState>,
254    pub(crate) router_orders: TopicRouter<OrderAny>,
255    pub(crate) router_positions: TopicRouter<Position>,
256    pub(crate) router_portfolio: TopicRouter<PortfolioSnapshot>,
257    pub(crate) router_greeks: TopicRouter<GreeksData>,
258    pub(crate) router_option_greeks: TopicRouter<OptionGreeks>,
259    pub(crate) router_option_chain: TopicRouter<OptionChainSlice>,
260    pub(crate) router_instruments: TopicRouter<InstrumentAny>,
261    #[cfg(feature = "defi")]
262    pub(crate) router_defi_blocks: TopicRouter<nautilus_model::defi::Block>, // nautilus-import-ok
263    #[cfg(feature = "defi")]
264    pub(crate) router_defi_pools: TopicRouter<nautilus_model::defi::Pool>, // nautilus-import-ok
265    #[cfg(feature = "defi")]
266    pub(crate) router_defi_swaps: TopicRouter<nautilus_model::defi::PoolSwap>, // nautilus-import-ok
267    #[cfg(feature = "defi")]
268    pub(crate) router_defi_liquidity: TopicRouter<nautilus_model::defi::PoolLiquidityUpdate>, // nautilus-import-ok
269    #[cfg(feature = "defi")]
270    pub(crate) router_defi_collects: TopicRouter<nautilus_model::defi::PoolFeeCollect>, // nautilus-import-ok
271    #[cfg(feature = "defi")]
272    pub(crate) router_defi_flash: TopicRouter<nautilus_model::defi::PoolFlash>, // nautilus-import-ok
273    #[cfg(feature = "defi")]
274    pub(crate) endpoints_defi_data: IntoEndpointMap<nautilus_model::defi::DefiData>, // nautilus-import-ok
275    pub(crate) endpoints_quotes: EndpointMap<QuoteTick>,
276    pub(crate) endpoints_trades: EndpointMap<TradeTick>,
277    pub(crate) endpoints_bars: EndpointMap<Bar>,
278    pub(crate) endpoints_account_state: EndpointMap<AccountState>,
279    pub(crate) endpoints_trading_commands: IntoEndpointMap<TradingCommand>,
280    pub(crate) endpoints_data_commands: IntoEndpointMap<DataCommand>,
281    pub(crate) endpoints_data_responses: IntoEndpointMap<DataResponse>,
282    pub(crate) endpoints_exec_reports: IntoEndpointMap<ExecutionReport>,
283    pub(crate) endpoints_order_events: IntoEndpointMap<OrderEventAny>,
284    pub(crate) endpoints_data: IntoEndpointMap<Data>,
285    routers_typed: AHashMap<TypeId, Box<dyn Any>>,
286    endpoints_typed: AHashMap<TypeId, Box<dyn Any>>,
287    sent_count: u64,
288    req_count: u64,
289    res_count: u64,
290    pub_count: u64,
291    external_egress: Option<Rc<RefCell<Box<dyn MessageBusExternalEgress>>>>,
292    has_external_streams: bool,
293    has_external_data_ingress: bool,
294    encoding: SerializationEncoding,
295    encoding_market_data: Option<SerializationEncoding>,
296    encoding_builtin: Option<SerializationEncoding>,
297    timestamps_as_iso8601: bool,
298    types_filter: AHashSet<BusPayloadType>,
299    streaming_types: AHashSet<BusPayloadType>,
300}
301
302impl Debug for MessageBus {
303    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
304        f.debug_struct(stringify!(MessageBus))
305            .field("trader_id", &self.trader_id)
306            .field("instance_id", &self.instance_id)
307            .field("name", &self.name)
308            .field("has_backing", &self.has_backing)
309            .field("external_egress", &self.external_egress.is_some())
310            .finish_non_exhaustive()
311    }
312}
313
314impl Default for MessageBus {
315    /// Creates a new default [`MessageBus`] instance.
316    fn default() -> Self {
317        Self::new(TraderId::from("TRADER-001"), UUID4::new(), None, None)
318    }
319}
320
321impl MessageBus {
322    /// Creates a new [`MessageBus`] instance.
323    #[must_use]
324    pub fn new(
325        trader_id: TraderId,
326        instance_id: UUID4,
327        name: Option<String>,
328        _config: Option<HashMap<String, serde_json::Value>>,
329    ) -> Self {
330        Self {
331            trader_id,
332            instance_id,
333            name: name.unwrap_or(stringify!(MessageBus).to_owned()),
334            switchboard: MessagingSwitchboard::default(),
335            subscriptions: AHashSet::new(),
336            topics: IndexMap::new(),
337            endpoints: IndexMap::new(),
338            correlation_index: AHashMap::new(),
339            has_backing: false,
340            router_quotes: TopicRouter::new(),
341            router_trades: TopicRouter::new(),
342            router_bars: TopicRouter::new(),
343            router_deltas: TopicRouter::new(),
344            router_depth: TopicRouter::new(),
345            router_book_snapshots: TopicRouter::new(),
346            router_mark_prices: TopicRouter::new(),
347            router_index_prices: TopicRouter::new(),
348            router_funding_rates: TopicRouter::new(),
349            router_order_events: TopicRouter::new(),
350            router_position_events: TopicRouter::new(),
351            router_account_state: TopicRouter::new(),
352            router_portfolio: TopicRouter::new(),
353            router_orders: TopicRouter::new(),
354            router_positions: TopicRouter::new(),
355            router_greeks: TopicRouter::new(),
356            router_option_greeks: TopicRouter::new(),
357            router_option_chain: TopicRouter::new(),
358            router_instruments: TopicRouter::new(),
359            #[cfg(feature = "defi")]
360            router_defi_blocks: TopicRouter::new(),
361            #[cfg(feature = "defi")]
362            router_defi_pools: TopicRouter::new(),
363            #[cfg(feature = "defi")]
364            router_defi_swaps: TopicRouter::new(),
365            #[cfg(feature = "defi")]
366            router_defi_liquidity: TopicRouter::new(),
367            #[cfg(feature = "defi")]
368            router_defi_collects: TopicRouter::new(),
369            #[cfg(feature = "defi")]
370            router_defi_flash: TopicRouter::new(),
371            #[cfg(feature = "defi")]
372            endpoints_defi_data: IntoEndpointMap::new(),
373            endpoints_quotes: EndpointMap::new(),
374            endpoints_trades: EndpointMap::new(),
375            endpoints_bars: EndpointMap::new(),
376            endpoints_account_state: EndpointMap::new(),
377            endpoints_trading_commands: IntoEndpointMap::new(),
378            endpoints_data_commands: IntoEndpointMap::new(),
379            endpoints_data_responses: IntoEndpointMap::new(),
380            endpoints_exec_reports: IntoEndpointMap::new(),
381            endpoints_order_events: IntoEndpointMap::new(),
382            endpoints_data: IntoEndpointMap::new(),
383            routers_typed: AHashMap::new(),
384            endpoints_typed: AHashMap::new(),
385            sent_count: 0,
386            req_count: 0,
387            res_count: 0,
388            pub_count: 0,
389            external_egress: None,
390            has_external_streams: false,
391            has_external_data_ingress: false,
392            encoding: SerializationEncoding::Json,
393            encoding_market_data: None,
394            encoding_builtin: None,
395            timestamps_as_iso8601: false,
396            types_filter: AHashSet::new(),
397            streaming_types: AHashSet::new(),
398        }
399    }
400
401    /// Registers message bus for the current thread.
402    pub fn register_message_bus(self) -> Rc<RefCell<Self>> {
403        let msgbus = Rc::new(RefCell::new(self));
404        set_message_bus(msgbus.clone());
405        msgbus
406    }
407
408    /// Gets or creates a typed router for custom message type `T`.
409    ///
410    /// # Panics
411    ///
412    /// Panics if the stored router type doesn't match `T` (internal bug).
413    pub fn router<T: 'static>(&mut self) -> &mut TopicRouter<T> {
414        self.routers_typed
415            .entry(TypeId::of::<T>())
416            .or_insert_with(|| Box::new(TopicRouter::<T>::new()))
417            .downcast_mut::<TopicRouter<T>>()
418            .expect("TopicRouter type mismatch - this is a bug")
419    }
420
421    /// Gets or creates a typed endpoint map for custom message type `T`.
422    ///
423    /// # Panics
424    ///
425    /// Panics if the stored endpoint map type doesn't match `T` (internal bug).
426    pub fn endpoint_map<T: 'static>(&mut self) -> &mut EndpointMap<T> {
427        self.endpoints_typed
428            .entry(TypeId::of::<T>())
429            .or_insert_with(|| Box::new(EndpointMap::<T>::new()))
430            .downcast_mut::<EndpointMap<T>>()
431            .expect("EndpointMap type mismatch - this is a bug")
432    }
433
434    /// Sets external egress for serialized published messages.
435    ///
436    /// Typed message variants remain local because this method does not configure external streams.
437    pub fn set_external_egress(
438        &mut self,
439        external_egress: Box<dyn MessageBusExternalEgress>,
440        encoding: SerializationEncoding,
441    ) {
442        self.external_egress = Some(Rc::new(RefCell::new(external_egress)));
443        self.has_external_streams = false;
444        self.encoding = encoding;
445        self.encoding_market_data = None;
446        self.encoding_builtin = None;
447        self.timestamps_as_iso8601 = false;
448        self.has_backing = true;
449        HAS_EXTERNAL_EGRESS.with(|flag| flag.set(true));
450    }
451
452    /// Sets external egress and category encoding policy from a validated config.
453    ///
454    /// Typed message variants are enabled only when `config.external_streams` is non-empty.
455    ///
456    /// # Errors
457    ///
458    /// Returns an error if the config selects an unsupported encoding.
459    pub fn set_external_egress_config(
460        &mut self,
461        external_egress: Box<dyn MessageBusExternalEgress>,
462        config: &MessageBusConfig,
463    ) -> crate::config::ConfigResult<()> {
464        config.validate()?;
465
466        self.external_egress = Some(Rc::new(RefCell::new(external_egress)));
467        self.has_external_streams = config
468            .external_streams
469            .as_ref()
470            .is_some_and(|streams| !streams.is_empty());
471        self.encoding = config.encoding;
472        self.encoding_market_data = config.encoding_market_data;
473        self.encoding_builtin = config.encoding_builtin;
474        self.timestamps_as_iso8601 = config.timestamps_as_iso8601;
475        self.has_backing = true;
476        HAS_EXTERNAL_EGRESS.with(|flag| flag.set(true));
477
478        Ok(())
479    }
480
481    /// Sets the payload type names excluded from external publishing.
482    pub fn set_types_filter(&mut self, filter: Vec<String>) {
483        self.types_filter.clear();
484
485        for type_name in filter {
486            let payload_type = BusPayloadType::from_name(&type_name);
487            if !payload_type.as_str().is_empty() {
488                self.types_filter.insert(payload_type);
489            }
490
491            if let Some(payload_type) = BusPayloadType::from_typed_name(&type_name) {
492                self.types_filter.insert(payload_type);
493            }
494        }
495    }
496
497    /// Registers a payload type for external-to-internal streaming.
498    pub fn add_streaming_type(&mut self, payload_type: BusPayloadType) {
499        if !payload_type.as_str().is_empty() {
500            self.streaming_types.insert(payload_type);
501        }
502    }
503
504    /// Returns whether the payload type is registered for external-to-internal streaming.
505    #[must_use]
506    pub fn is_streaming_type(&self, payload_type: BusPayloadType) -> bool {
507        !payload_type.as_str().is_empty() && self.streaming_types.contains(&payload_type)
508    }
509
510    /// Clears all payload types registered for external-to-internal streaming.
511    pub fn clear_streaming_types(&mut self) {
512        self.streaming_types.clear();
513    }
514
515    #[must_use]
516    pub(crate) fn has_external_egress(&self) -> bool {
517        self.external_egress.is_some()
518    }
519
520    pub(crate) fn has_external_streams(&self) -> bool {
521        self.has_external_streams
522    }
523
524    /// Sets whether inbound market data can use the `DataEngine` process-data endpoint.
525    ///
526    /// `DataEngine` sets this when registering its message bus handlers. The active bus mirrors
527    /// this value in thread-local storage for a fast eligibility check.
528    pub fn set_external_data_ingress(&mut self, enabled: bool) {
529        self.has_external_data_ingress = enabled;
530        if try_get_message_bus().is_some_and(|bus| eq(bus.as_ptr(), self)) {
531            HAS_EXTERNAL_DATA_INGRESS.with(|flag| flag.set(enabled));
532        }
533    }
534
535    pub(super) fn has_external_data_ingress(&self) -> bool {
536        self.has_external_data_ingress
537    }
538
539    pub(crate) fn external_egress(&self) -> Option<Rc<RefCell<Box<dyn MessageBusExternalEgress>>>> {
540        self.external_egress.clone()
541    }
542
543    pub(crate) fn encoding_for(&self, payload_type: BusPayloadType) -> SerializationEncoding {
544        match payload_type.category() {
545            BusPayloadCategory::MarketData => self.encoding_market_data.unwrap_or(self.encoding),
546            BusPayloadCategory::BuiltIn => self.encoding_builtin.unwrap_or(self.encoding),
547            BusPayloadCategory::Other => self.encoding,
548        }
549    }
550
551    pub(crate) fn timestamps_as_iso8601(&self) -> bool {
552        self.timestamps_as_iso8601
553    }
554
555    pub(crate) fn types_filter(&self) -> &AHashSet<BusPayloadType> {
556        &self.types_filter
557    }
558
559    /// Disposes of the message bus, clearing all subscriptions, endpoints,
560    /// and handler references.
561    pub fn dispose(&mut self) {
562        self.subscriptions.clear();
563        self.topics.clear();
564        self.endpoints.clear();
565        self.correlation_index.clear();
566
567        self.router_quotes.clear();
568        self.router_trades.clear();
569        self.router_bars.clear();
570        self.router_deltas.clear();
571        self.router_depth.clear();
572        self.router_book_snapshots.clear();
573        self.router_mark_prices.clear();
574        self.router_index_prices.clear();
575        self.router_funding_rates.clear();
576        self.router_order_events.clear();
577        self.router_position_events.clear();
578        self.router_account_state.clear();
579        self.router_portfolio.clear();
580        self.router_orders.clear();
581        self.router_positions.clear();
582        self.router_greeks.clear();
583        self.router_option_greeks.clear();
584        self.router_option_chain.clear();
585        self.router_instruments.clear();
586
587        #[cfg(feature = "defi")]
588        {
589            self.router_defi_blocks.clear();
590            self.router_defi_pools.clear();
591            self.router_defi_swaps.clear();
592            self.router_defi_liquidity.clear();
593            self.router_defi_collects.clear();
594            self.router_defi_flash.clear();
595            self.endpoints_defi_data.clear();
596        }
597
598        self.endpoints_quotes.clear();
599        self.endpoints_trades.clear();
600        self.endpoints_bars.clear();
601        self.endpoints_account_state.clear();
602        self.endpoints_trading_commands.clear();
603        self.endpoints_data_commands.clear();
604        self.endpoints_data_responses.clear();
605        self.endpoints_exec_reports.clear();
606        self.endpoints_order_events.clear();
607        self.endpoints_data.clear();
608        self.set_external_data_ingress(false);
609        self.routers_typed.clear();
610        self.endpoints_typed.clear();
611        self.clear_streaming_types();
612        self.sent_count = 0;
613        self.req_count = 0;
614        self.res_count = 0;
615        self.pub_count = 0;
616
617        if let Some(external_egress) = self.external_egress.take() {
618            external_egress.borrow_mut().close();
619        }
620        self.has_external_streams = false;
621        self.has_backing = false;
622        HAS_EXTERNAL_EGRESS.with(|flag| flag.set(false));
623    }
624
625    /// Returns the memory address of this instance as a hexadecimal string.
626    #[must_use]
627    pub fn mem_address(&self) -> String {
628        format!("{self:p}")
629    }
630
631    /// Returns a reference to the switchboard.
632    #[must_use]
633    pub fn switchboard(&self) -> &MessagingSwitchboard {
634        &self.switchboard
635    }
636
637    /// Returns the total count of messages sent to endpoints.
638    #[must_use]
639    pub const fn sent_count(&self) -> u64 {
640        self.sent_count
641    }
642
643    /// Returns the total count of requests sent to endpoints.
644    #[must_use]
645    pub const fn req_count(&self) -> u64 {
646        self.req_count
647    }
648
649    /// Returns the total count of responses sent to registered handlers.
650    #[must_use]
651    pub const fn res_count(&self) -> u64 {
652        self.res_count
653    }
654
655    /// Returns the total count of messages published to topics.
656    #[must_use]
657    pub const fn pub_count(&self) -> u64 {
658        self.pub_count
659    }
660
661    pub(crate) fn increment_sent_count(&mut self) {
662        self.sent_count += 1;
663    }
664
665    pub(crate) fn increment_req_count(&mut self) {
666        self.req_count += 1;
667    }
668
669    pub(crate) fn increment_res_count(&mut self) {
670        self.res_count += 1;
671    }
672
673    pub(crate) fn increment_pub_count(&mut self) {
674        self.pub_count += 1;
675    }
676
677    /// Returns the registered endpoint addresses.
678    #[must_use]
679    pub fn endpoints(&self) -> Vec<&str> {
680        self.endpoints.iter().map(|e| e.0.as_str()).collect()
681    }
682
683    /// Returns actively subscribed patterns.
684    #[must_use]
685    pub fn patterns(&self) -> Vec<&str> {
686        self.subscriptions
687            .iter()
688            .map(|s| s.pattern.as_str())
689            .collect()
690    }
691
692    /// Returns whether there are subscribers for the `topic`.
693    ///
694    /// # Errors
695    ///
696    /// Returns an error if the `topic` is not a valid topic string.
697    pub fn has_subscribers<T: AsRef<str>>(&self, topic: T) -> anyhow::Result<bool> {
698        Ok(self.subscriptions_count(topic)? > 0)
699    }
700
701    /// Returns the count of subscribers for the `topic`.
702    ///
703    /// # Errors
704    ///
705    /// Returns an error if the `topic` is not a valid topic string.
706    pub fn subscriptions_count<T: AsRef<str>>(&self, topic: T) -> anyhow::Result<usize> {
707        let topic = MStr::<Topic>::topic(topic)?;
708        Ok(self
709            .topics
710            .get(&topic)
711            .map_or_else(|| self.find_topic_matches(topic).len(), Vec::len))
712    }
713
714    /// Returns active subscriptions.
715    #[must_use]
716    pub fn subscriptions(&self) -> Vec<&Subscription> {
717        self.subscriptions.iter().collect()
718    }
719
720    /// Returns the handler IDs for actively subscribed patterns.
721    #[must_use]
722    pub fn subscription_handler_ids(&self) -> Vec<&str> {
723        self.subscriptions
724            .iter()
725            .map(|s| s.handler_id.as_str())
726            .collect()
727    }
728
729    /// Returns whether the endpoint is registered.
730    ///
731    /// # Panics
732    ///
733    /// Panics if the `endpoint` conversion to `MStr<Endpoint>` fails.
734    #[must_use]
735    pub fn is_registered<T: Into<MStr<Endpoint>>>(&self, endpoint: T) -> bool {
736        let endpoint: MStr<Endpoint> = endpoint.into();
737        self.endpoints.contains_key(&endpoint)
738    }
739
740    /// Returns whether the `handler` is subscribed to the `pattern`.
741    #[must_use]
742    pub fn is_subscribed<T: AsRef<str>>(
743        &self,
744        pattern: T,
745        handler: ShareableMessageHandler,
746    ) -> bool {
747        let pattern = MStr::<Pattern>::pattern(pattern);
748        let sub = Subscription::new(pattern, handler, None);
749        self.subscriptions.contains(&sub)
750    }
751
752    /// Close the message bus which will close the sender channel and join the thread.
753    ///
754    /// This function does not return an error.
755    #[allow(
756        clippy::missing_errors_doc,
757        reason = "closing the in-memory message bus returns no errors"
758    )]
759    pub fn close(&mut self) -> anyhow::Result<()> {
760        if let Some(external_egress) = self.external_egress.take() {
761            external_egress.borrow_mut().close();
762        }
763        self.has_external_streams = false;
764        self.has_backing = false;
765        HAS_EXTERNAL_EGRESS.with(|flag| flag.set(false));
766        Ok(())
767    }
768
769    /// Returns the handler for the `endpoint`.
770    #[must_use]
771    pub fn get_endpoint(&self, endpoint: MStr<Endpoint>) -> Option<&ShareableMessageHandler> {
772        self.endpoints.get(&endpoint)
773    }
774
775    /// Returns the handler for the `correlation_id`.
776    #[must_use]
777    pub fn get_response_handler(
778        &self,
779        correlation_id: &UUID4,
780    ) -> Option<&TypedHandler<DataResponseEnvelope>> {
781        self.correlation_index.get(correlation_id)
782    }
783
784    /// Removes and returns the handler for the `correlation_id`.
785    pub fn take_response_handler(
786        &mut self,
787        correlation_id: &UUID4,
788    ) -> Option<TypedHandler<DataResponseEnvelope>> {
789        self.correlation_index.remove(correlation_id)
790    }
791
792    /// Finds the subscriptions with pattern matching the `topic`.
793    fn find_topic_matches(&self, topic: MStr<Topic>) -> Vec<Subscription> {
794        self.subscriptions
795            .iter()
796            .filter_map(|sub| {
797                if is_matching_backtracking(topic, sub.pattern) {
798                    Some(sub.clone())
799                } else {
800                    None
801                }
802            })
803            .collect()
804    }
805
806    /// Finds the subscriptions which match the `topic` and caches the
807    /// results in the `patterns` map.
808    #[must_use]
809    pub fn matching_subscriptions<T: Into<MStr<Topic>>>(&mut self, topic: T) -> Vec<Subscription> {
810        self.inner_matching_subscriptions(topic.into())
811    }
812
813    fn inner_matching_subscriptions(&mut self, topic: MStr<Topic>) -> Vec<Subscription> {
814        self.topics.get(&topic).cloned().unwrap_or_else(|| {
815            let mut matches = self.find_topic_matches(topic);
816            matches.sort_by(Subscription::delivery_order);
817            self.topics.insert(topic, matches.clone());
818            matches
819        })
820    }
821
822    /// Fills a buffer with handlers matching a topic.
823    pub(crate) fn fill_matching_any_handlers(
824        &mut self,
825        topic: MStr<Topic>,
826        buf: &mut SmallVec<[ShareableMessageHandler; 64]>,
827    ) {
828        if let Some(subs) = self.topics.get(&topic) {
829            for sub in subs {
830                buf.push(sub.handler.clone());
831            }
832        } else {
833            let mut matches = self.find_topic_matches(topic);
834            matches.sort_by(Subscription::delivery_order);
835
836            for sub in &matches {
837                buf.push(sub.handler.clone());
838            }
839
840            self.topics.insert(topic, matches);
841        }
842    }
843
844    /// Registers a response handler for a specific correlation ID.
845    ///
846    /// # Errors
847    ///
848    /// Returns an error if `handler` is already registered for the `correlation_id`.
849    pub fn register_response_handler(
850        &mut self,
851        correlation_id: &UUID4,
852        handler: TypedHandler<DataResponseEnvelope>,
853    ) -> anyhow::Result<()> {
854        if self.correlation_index.contains_key(correlation_id) {
855            anyhow::bail!("Correlation ID <{correlation_id}> already has a registered handler");
856        }
857
858        self.correlation_index.insert(*correlation_id, handler);
859
860        Ok(())
861    }
862
863    pub(crate) fn unsubscribe_any(
864        &mut self,
865        pattern: MStr<Pattern>,
866        handler: &ShareableMessageHandler,
867    ) {
868        log::debug!("Unsubscribing {handler:?} from pattern '{pattern}'");
869
870        let handler_id = handler.0.id();
871
872        let count_before = self.subscriptions.len();
873
874        self.topics.values_mut().for_each(|subs| {
875            subs.retain(|s| !(s.pattern == pattern && s.handler_id == handler_id));
876        });
877
878        self.subscriptions
879            .retain(|s| !(s.pattern == pattern && s.handler_id == handler_id));
880
881        let removed = self.subscriptions.len() < count_before;
882
883        if removed {
884            log::debug!("Handler for pattern '{pattern}' was removed");
885        } else {
886            log::debug!("No matching handler for pattern '{pattern}' was found");
887        }
888    }
889}
890
891#[cfg(test)]
892mod tests {
893    use std::{
894        any::Any,
895        cell::RefCell,
896        collections::hash_map::DefaultHasher,
897        fmt::Debug,
898        hash::{Hash, Hasher},
899        rc::Rc,
900    };
901
902    use rand::{RngExt, SeedableRng, rngs::StdRng};
903    use rstest::rstest;
904    use ustr::Ustr;
905
906    use super::*;
907    use crate::msgbus::{
908        self, Handler, ShareableMessageHandler, get_message_bus,
909        matching::is_matching_backtracking,
910        stubs::{get_any_saving_handler, get_call_check_handler, get_stub_shareable_handler},
911        subscriptions_count_any,
912        typed_handler::shareable_handler,
913    };
914
915    #[derive(Debug)]
916    struct RecordingAnyHandler {
917        id: Ustr,
918        label: &'static str,
919        order: Rc<RefCell<Vec<&'static str>>>,
920    }
921
922    impl Handler<dyn Any> for RecordingAnyHandler {
923        fn id(&self) -> Ustr {
924            self.id
925        }
926
927        fn handle(&self, _message: &dyn Any) {
928            self.order.borrow_mut().push(self.label);
929        }
930    }
931
932    fn recording_any_handler(
933        id: &'static str,
934        label: &'static str,
935        order: Rc<RefCell<Vec<&'static str>>>,
936    ) -> ShareableMessageHandler {
937        shareable_handler(Rc::new(RecordingAnyHandler {
938            id: Ustr::from(id),
939            label,
940            order,
941        }))
942    }
943
944    #[rstest]
945    fn test_subscription_ordering_laws() {
946        let handler = get_stub_shareable_handler(Some(Ustr::from("handler-b")));
947        let base = Subscription::new("pattern-b".into(), handler.clone(), Some(1));
948        let different_priority = Subscription::new("pattern-b".into(), handler, Some(2));
949        let different_pattern = Subscription::new(
950            "pattern-a".into(),
951            get_stub_shareable_handler(Some(Ustr::from("handler-b"))),
952            Some(1),
953        );
954        let different_handler = Subscription::new(
955            "pattern-b".into(),
956            get_stub_shareable_handler(Some(Ustr::from("handler-a"))),
957            Some(1),
958        );
959
960        assert_eq!(base, different_priority);
961        assert_eq!(base.cmp(&different_priority), std::cmp::Ordering::Equal);
962
963        let mut base_hasher = DefaultHasher::new();
964        base.hash(&mut base_hasher);
965        let mut different_priority_hasher = DefaultHasher::new();
966        different_priority.hash(&mut different_priority_hasher);
967        assert_eq!(base_hasher.finish(), different_priority_hasher.finish());
968
969        let variants = [
970            base,
971            different_priority,
972            different_pattern,
973            different_handler,
974        ];
975
976        for a in &variants {
977            for b in &variants {
978                assert_eq!(a == b, a.cmp(b).is_eq());
979                assert_eq!(a.partial_cmp(b), Some(a.cmp(b)));
980                assert_eq!(a.cmp(b), b.cmp(a).reverse());
981            }
982        }
983    }
984
985    #[rstest]
986    fn test_new() {
987        let trader_id = TraderId::default();
988        let msgbus = MessageBus::new(trader_id, UUID4::new(), None, None);
989
990        assert_eq!(msgbus.trader_id, trader_id);
991        assert_eq!(msgbus.name, stringify!(MessageBus));
992    }
993
994    #[rstest]
995    fn encoding_for_uses_market_data_override() {
996        let msgbus = MessageBus {
997            encoding: SerializationEncoding::Json,
998            encoding_market_data: Some(SerializationEncoding::MsgPack),
999            ..Default::default()
1000        };
1001
1002        assert_eq!(
1003            msgbus.encoding_for(BusPayloadType::QuoteTick),
1004            SerializationEncoding::MsgPack
1005        );
1006        assert_eq!(
1007            msgbus.encoding_for(BusPayloadType::Custom(Ustr::from("CustomPayload"))),
1008            SerializationEncoding::Json
1009        );
1010    }
1011
1012    #[rstest]
1013    fn encoding_for_uses_builtin_override() {
1014        let msgbus = MessageBus {
1015            encoding: SerializationEncoding::Json,
1016            encoding_builtin: Some(SerializationEncoding::MsgPack),
1017            ..Default::default()
1018        };
1019
1020        assert_eq!(
1021            msgbus.encoding_for(BusPayloadType::OrderEvent),
1022            SerializationEncoding::MsgPack
1023        );
1024        assert_eq!(
1025            msgbus.encoding_for(BusPayloadType::Instrument),
1026            SerializationEncoding::Json
1027        );
1028    }
1029
1030    #[rstest]
1031    fn encoding_for_uses_default_without_category_override() {
1032        let msgbus = MessageBus {
1033            encoding: SerializationEncoding::MsgPack,
1034            ..Default::default()
1035        };
1036
1037        assert_eq!(
1038            msgbus.encoding_for(BusPayloadType::QuoteTick),
1039            SerializationEncoding::MsgPack
1040        );
1041        assert_eq!(
1042            msgbus.encoding_for(BusPayloadType::OrderEvent),
1043            SerializationEncoding::MsgPack
1044        );
1045        assert_eq!(
1046            msgbus.encoding_for(BusPayloadType::Custom(Ustr::from("CustomPayload"))),
1047            SerializationEncoding::MsgPack
1048        );
1049    }
1050
1051    #[rstest]
1052    fn set_types_filter_resolves_untyped_and_typed_names() {
1053        let mut msgbus = MessageBus::default();
1054
1055        msgbus.set_types_filter(vec![
1056            "QuoteTick".to_string(),
1057            "ExternalCustomPayload".to_string(),
1058            "OrderStatusReport".to_string(),
1059            String::new(),
1060        ]);
1061
1062        let filter = msgbus.types_filter();
1063        assert_eq!(filter.len(), 4);
1064        assert!(filter.contains(&BusPayloadType::QuoteTick));
1065        assert!(filter.contains(&BusPayloadType::Custom(Ustr::from("ExternalCustomPayload"))));
1066        assert!(filter.contains(&BusPayloadType::Custom(Ustr::from("OrderStatusReport"))));
1067        assert!(filter.contains(&BusPayloadType::OrderStatusReport));
1068        assert!(!filter.contains(&BusPayloadType::Custom(Ustr::default())));
1069    }
1070
1071    #[rstest]
1072    fn streaming_type_registration_uses_canonical_payload_names() {
1073        let mut msgbus = MessageBus::default();
1074
1075        msgbus.add_streaming_type(BusPayloadType::QuoteTick);
1076        msgbus.add_streaming_type(BusPayloadType::Custom(Ustr::from("CustomPayload")));
1077
1078        assert!(msgbus.is_streaming_type(BusPayloadType::QuoteTick));
1079        assert!(msgbus.is_streaming_type(BusPayloadType::Custom(Ustr::from("CustomPayload"))));
1080        assert!(msgbus.streaming_types.contains(&BusPayloadType::QuoteTick));
1081        assert!(
1082            msgbus
1083                .streaming_types
1084                .contains(&BusPayloadType::Custom(Ustr::from("CustomPayload")))
1085        );
1086        assert!(!msgbus.is_streaming_type(BusPayloadType::TradeTick));
1087    }
1088
1089    #[rstest]
1090    fn streaming_type_registration_ignores_empty_custom_payload_type() {
1091        let mut msgbus = MessageBus::default();
1092
1093        msgbus.add_streaming_type(BusPayloadType::Custom(Ustr::default()));
1094
1095        assert!(!msgbus.is_streaming_type(BusPayloadType::Custom(Ustr::default())));
1096        assert!(msgbus.streaming_types.is_empty());
1097    }
1098
1099    #[rstest]
1100    fn clear_streaming_types_removes_registered_types() {
1101        let mut msgbus = MessageBus::default();
1102        msgbus.add_streaming_type(BusPayloadType::QuoteTick);
1103
1104        msgbus.clear_streaming_types();
1105
1106        assert!(!msgbus.is_streaming_type(BusPayloadType::QuoteTick));
1107    }
1108
1109    #[rstest]
1110    fn dispose_clears_streaming_types() {
1111        let mut msgbus = MessageBus::default();
1112        msgbus.add_streaming_type(BusPayloadType::QuoteTick);
1113
1114        msgbus.dispose();
1115
1116        assert!(!msgbus.is_streaming_type(BusPayloadType::QuoteTick));
1117    }
1118
1119    #[rstest]
1120    fn test_dispose_resets_counters() {
1121        let mut msgbus = MessageBus::default();
1122
1123        msgbus.increment_sent_count();
1124        msgbus.increment_req_count();
1125        msgbus.increment_res_count();
1126        msgbus.increment_pub_count();
1127        msgbus.dispose();
1128
1129        assert_eq!(msgbus.sent_count(), 0);
1130        assert_eq!(msgbus.req_count(), 0);
1131        assert_eq!(msgbus.res_count(), 0);
1132        assert_eq!(msgbus.pub_count(), 0);
1133    }
1134
1135    #[rstest]
1136    fn test_endpoints_when_no_endpoints() {
1137        let msgbus = get_message_bus();
1138        assert!(msgbus.borrow().endpoints().is_empty());
1139    }
1140
1141    #[rstest]
1142    fn test_topics_when_no_subscriptions() {
1143        let msgbus = get_message_bus();
1144        assert!(msgbus.borrow().patterns().is_empty());
1145        assert!(!msgbus.borrow().has_subscribers("my-topic").unwrap());
1146    }
1147
1148    #[rstest]
1149    fn test_is_subscribed_when_no_subscriptions() {
1150        let msgbus = get_message_bus();
1151        let handler = get_stub_shareable_handler(None);
1152
1153        assert!(!msgbus.borrow().is_subscribed("my-topic", handler));
1154    }
1155
1156    #[rstest]
1157    fn test_get_response_handler_when_no_handler() {
1158        let msgbus = get_message_bus();
1159        let msgbus_ref = msgbus.borrow();
1160        let handler = msgbus_ref.get_response_handler(&UUID4::new());
1161        assert!(handler.is_none());
1162    }
1163
1164    #[rstest]
1165    fn test_get_response_handler_when_already_registered() {
1166        let msgbus = get_message_bus();
1167        let mut msgbus_ref = msgbus.borrow_mut();
1168        let handler = TypedHandler::from(|_: &DataResponseEnvelope| {});
1169
1170        let request_id = UUID4::new();
1171        msgbus_ref
1172            .register_response_handler(&request_id, handler.clone())
1173            .unwrap();
1174
1175        let result = msgbus_ref.register_response_handler(&request_id, handler);
1176        assert!(result.is_err());
1177    }
1178
1179    #[rstest]
1180    fn test_get_response_handler_when_registered() {
1181        let msgbus = get_message_bus();
1182        let mut msgbus_ref = msgbus.borrow_mut();
1183        let handler = TypedHandler::from(|_: &DataResponseEnvelope| {});
1184
1185        let expected_id = handler.id();
1186        let request_id = UUID4::new();
1187        msgbus_ref
1188            .register_response_handler(&request_id, handler)
1189            .unwrap();
1190
1191        let handler = msgbus_ref.get_response_handler(&request_id).unwrap();
1192        assert_eq!(handler.id(), expected_id);
1193    }
1194
1195    #[rstest]
1196    fn test_take_response_handler_removes_registration_and_allows_reregistration() {
1197        let mut msgbus = MessageBus::default();
1198        let request_id = UUID4::new();
1199        let handler = TypedHandler::from(|_: &DataResponseEnvelope| {});
1200        let handler_id = handler.id();
1201        msgbus
1202            .register_response_handler(&request_id, handler)
1203            .unwrap();
1204
1205        let taken = msgbus.take_response_handler(&request_id).unwrap();
1206
1207        assert_eq!(taken.id(), handler_id);
1208        assert!(msgbus.get_response_handler(&request_id).is_none());
1209        assert!(msgbus.register_response_handler(&request_id, taken).is_ok());
1210    }
1211
1212    #[rstest]
1213    fn test_is_registered_when_no_registrations() {
1214        let msgbus = get_message_bus();
1215        assert!(!msgbus.borrow().is_registered("MyEndpoint"));
1216    }
1217
1218    #[rstest]
1219    fn test_register_endpoint() {
1220        let msgbus = get_message_bus();
1221        let endpoint = "MyEndpoint".into();
1222        let handler = get_stub_shareable_handler(None);
1223
1224        msgbus::register_any(endpoint, handler);
1225
1226        assert_eq!(msgbus.borrow().endpoints(), vec![endpoint.to_string()]);
1227        assert!(msgbus.borrow().get_endpoint(endpoint).is_some());
1228    }
1229
1230    #[rstest]
1231    fn test_endpoint_send() {
1232        let msgbus = get_message_bus();
1233        let endpoint = "MyEndpoint".into();
1234        let (handler, checker) = get_call_check_handler(None);
1235        let sent_count = msgbus.borrow().sent_count();
1236
1237        msgbus::register_any(endpoint, handler);
1238        assert!(msgbus.borrow().get_endpoint(endpoint).is_some());
1239        assert!(!checker.was_called());
1240
1241        msgbus::send_any(endpoint, &"Test Message");
1242
1243        assert!(checker.was_called());
1244        assert_eq!(msgbus.borrow().sent_count(), sent_count + 1);
1245    }
1246
1247    #[rstest]
1248    fn test_endpoint_send_value_increments_sent_count() {
1249        let msgbus = get_message_bus();
1250        let endpoint = "MyValueEndpoint".into();
1251        let (handler, checker) = get_call_check_handler(None);
1252        let sent_count = msgbus.borrow().sent_count();
1253
1254        msgbus::register_any(endpoint, handler);
1255        msgbus::send_any_value(endpoint, &"Test Message");
1256
1257        assert!(checker.was_called());
1258        assert_eq!(msgbus.borrow().sent_count(), sent_count + 1);
1259    }
1260
1261    #[rstest]
1262    fn test_publish_any_increments_publish_count() {
1263        let msgbus = get_message_bus();
1264        let topic = "my-published-topic";
1265        let (handler, checker) = get_call_check_handler(None);
1266        let pub_count = msgbus.borrow().pub_count();
1267
1268        msgbus::subscribe_any(topic.into(), handler, None);
1269        msgbus::publish_any(topic.into(), &"Test Message");
1270
1271        assert!(checker.was_called());
1272        assert_eq!(msgbus.borrow().pub_count(), pub_count + 1);
1273    }
1274
1275    #[rstest]
1276    fn test_deregsiter_endpoint() {
1277        let msgbus = get_message_bus();
1278        let endpoint = "MyEndpoint".into();
1279        let handler = get_stub_shareable_handler(None);
1280
1281        msgbus::register_any(endpoint, handler);
1282        msgbus::deregister_any(endpoint);
1283
1284        assert!(msgbus.borrow().endpoints().is_empty());
1285    }
1286
1287    #[rstest]
1288    fn test_subscribe() {
1289        let msgbus = get_message_bus();
1290        let topic = "my-topic";
1291        let handler = get_stub_shareable_handler(None);
1292
1293        msgbus::subscribe_any(topic.into(), handler, Some(1));
1294
1295        assert!(msgbus.borrow().has_subscribers(topic).unwrap());
1296        assert_eq!(msgbus.borrow().patterns(), vec![topic]);
1297    }
1298
1299    #[rstest]
1300    fn test_unsubscribe() {
1301        let msgbus = get_message_bus();
1302        let topic = "my-topic";
1303        let handler = get_stub_shareable_handler(None);
1304
1305        msgbus::subscribe_any(topic.into(), handler.clone(), None);
1306        msgbus::unsubscribe_any(topic.into(), &handler);
1307
1308        assert!(!msgbus.borrow().has_subscribers(topic).unwrap());
1309        assert!(msgbus.borrow().patterns().is_empty());
1310    }
1311
1312    #[rstest]
1313    fn test_subscriptions_count_rejects_invalid_topic() {
1314        let msgbus = get_message_bus();
1315
1316        let err = msgbus
1317            .borrow()
1318            .subscriptions_count("data.*")
1319            .expect_err("wildcards are invalid in topics");
1320
1321        assert_eq!(
1322            err.to_string(),
1323            "Topic `value` contained invalid characters, was data.*"
1324        );
1325    }
1326
1327    #[rstest]
1328    fn test_has_subscribers_rejects_invalid_topic() {
1329        let msgbus = get_message_bus();
1330
1331        let err = msgbus
1332            .borrow()
1333            .has_subscribers("data.*")
1334            .expect_err("wildcards are invalid in topics");
1335
1336        assert_eq!(
1337            err.to_string(),
1338            "Topic `value` contained invalid characters, was data.*"
1339        );
1340    }
1341
1342    #[rstest]
1343    fn test_subscriptions_count_any_rejects_invalid_topic() {
1344        let err = subscriptions_count_any("data.*").expect_err("wildcards are invalid in topics");
1345
1346        assert_eq!(
1347            err.to_string(),
1348            "Topic `value` contained invalid characters, was data.*"
1349        );
1350    }
1351
1352    #[rstest]
1353    fn test_matching_subscriptions() {
1354        let msgbus = get_message_bus();
1355        let pattern = "my-pattern";
1356
1357        let handler_id1 = Ustr::from("1");
1358        let handler1 = get_stub_shareable_handler(Some(handler_id1));
1359
1360        let handler_id2 = Ustr::from("2");
1361        let handler2 = get_stub_shareable_handler(Some(handler_id2));
1362
1363        let handler_id3 = Ustr::from("3");
1364        let handler3 = get_stub_shareable_handler(Some(handler_id3));
1365
1366        let handler_id4 = Ustr::from("4");
1367        let handler4 = get_stub_shareable_handler(Some(handler_id4));
1368
1369        msgbus::subscribe_any(pattern.into(), handler1, None);
1370        msgbus::subscribe_any(pattern.into(), handler2, None);
1371        msgbus::subscribe_any(pattern.into(), handler3, Some(1));
1372        msgbus::subscribe_any(pattern.into(), handler4, Some(2));
1373
1374        assert_eq!(
1375            msgbus.borrow().patterns(),
1376            vec![pattern, pattern, pattern, pattern]
1377        );
1378        assert_eq!(subscriptions_count_any(pattern).unwrap(), 4);
1379
1380        let topic = pattern;
1381        let subs = msgbus.borrow_mut().matching_subscriptions(topic);
1382        assert_eq!(subs.len(), 4);
1383        assert_eq!(subs[0].handler_id, handler_id4);
1384        assert_eq!(subs[1].handler_id, handler_id3);
1385        assert_eq!(subs[2].handler_id, handler_id1);
1386        assert_eq!(subs[3].handler_id, handler_id2);
1387    }
1388
1389    #[rstest]
1390    fn test_matching_subscriptions_orders_by_full_delivery_key_on_cache_miss() {
1391        MessageBus::default().register_message_bus();
1392        let order = Rc::new(RefCell::new(Vec::new()));
1393
1394        msgbus::subscribe_any(
1395            "delivery.*".into(),
1396            recording_any_handler("handler-z", "low-z", order.clone()),
1397            Some(1),
1398        );
1399        msgbus::subscribe_any(
1400            "delivery.topic".into(),
1401            recording_any_handler("handler-b", "exact-b", order.clone()),
1402            Some(10),
1403        );
1404        msgbus::subscribe_any(
1405            "delivery.topic".into(),
1406            recording_any_handler("handler-a", "exact-a", order.clone()),
1407            Some(10),
1408        );
1409        msgbus::subscribe_any(
1410            "delivery.*".into(),
1411            recording_any_handler("handler-b", "wildcard-b", order),
1412            Some(10),
1413        );
1414
1415        let subscriptions = get_message_bus()
1416            .borrow_mut()
1417            .matching_subscriptions("delivery.topic");
1418        let actual = subscriptions
1419            .iter()
1420            .map(|sub| (sub.priority, sub.pattern.as_str(), sub.handler_id.as_str()))
1421            .collect::<Vec<_>>();
1422
1423        assert_eq!(
1424            actual,
1425            vec![
1426                (10, "delivery.*", "handler-b"),
1427                (10, "delivery.topic", "handler-a"),
1428                (10, "delivery.topic", "handler-b"),
1429                (1, "delivery.*", "handler-z"),
1430            ]
1431        );
1432    }
1433
1434    #[rstest]
1435    fn test_first_uncached_publish_any_orders_by_full_delivery_key() {
1436        MessageBus::default().register_message_bus();
1437        let order = Rc::new(RefCell::new(Vec::new()));
1438
1439        msgbus::subscribe_any(
1440            "delivery.*".into(),
1441            recording_any_handler("handler-z", "low-z", order.clone()),
1442            Some(1),
1443        );
1444        msgbus::subscribe_any(
1445            "delivery.topic".into(),
1446            recording_any_handler("handler-b", "exact-b", order.clone()),
1447            Some(10),
1448        );
1449        msgbus::subscribe_any(
1450            "delivery.topic".into(),
1451            recording_any_handler("handler-a", "exact-a", order.clone()),
1452            Some(10),
1453        );
1454        msgbus::subscribe_any(
1455            "delivery.*".into(),
1456            recording_any_handler("handler-b", "wildcard-b", order.clone()),
1457            Some(10),
1458        );
1459
1460        msgbus::publish_any("delivery.topic".into(), &());
1461
1462        assert_eq!(
1463            *order.borrow(),
1464            vec!["wildcard-b", "exact-a", "exact-b", "low-z"]
1465        );
1466    }
1467
1468    #[rstest]
1469    fn test_late_subscription_orders_cached_any_topic_by_full_delivery_key() {
1470        MessageBus::default().register_message_bus();
1471        let order = Rc::new(RefCell::new(Vec::new()));
1472
1473        msgbus::subscribe_any(
1474            "delivery.*".into(),
1475            recording_any_handler("handler-z", "low-z", order.clone()),
1476            Some(1),
1477        );
1478        msgbus::subscribe_any(
1479            "delivery.topic".into(),
1480            recording_any_handler("handler-b", "exact-b", order.clone()),
1481            Some(10),
1482        );
1483        msgbus::subscribe_any(
1484            "delivery.topic".into(),
1485            recording_any_handler("handler-a", "exact-a", order.clone()),
1486            Some(10),
1487        );
1488        msgbus::publish_any("delivery.topic".into(), &());
1489        order.borrow_mut().clear();
1490
1491        msgbus::subscribe_any(
1492            "delivery.*".into(),
1493            recording_any_handler("handler-b", "wildcard-b", order.clone()),
1494            Some(10),
1495        );
1496        msgbus::publish_any("delivery.topic".into(), &());
1497
1498        assert_eq!(
1499            *order.borrow(),
1500            vec!["wildcard-b", "exact-a", "exact-b", "low-z"]
1501        );
1502    }
1503
1504    #[rstest]
1505    fn test_subscription_pattern_matching() {
1506        let msgbus = get_message_bus();
1507        let handler1 = get_stub_shareable_handler(Some(Ustr::from("1")));
1508        let handler2 = get_stub_shareable_handler(Some(Ustr::from("2")));
1509        let handler3 = get_stub_shareable_handler(Some(Ustr::from("3")));
1510
1511        msgbus::subscribe_any("data.quotes.*".into(), handler1, None);
1512        msgbus::subscribe_any("data.trades.*".into(), handler2, None);
1513        msgbus::subscribe_any("data.*.BINANCE.*".into(), handler3, None);
1514        assert_eq!(msgbus.borrow().subscriptions().len(), 3);
1515
1516        let topic = "data.quotes.BINANCE.ETHUSDT";
1517        assert_eq!(msgbus.borrow().find_topic_matches(topic.into()).len(), 2);
1518
1519        let matches = msgbus.borrow_mut().matching_subscriptions(topic);
1520        assert_eq!(matches.len(), 2);
1521        assert_eq!(matches[0].handler_id, Ustr::from("3"));
1522        assert_eq!(matches[1].handler_id, Ustr::from("1"));
1523    }
1524
1525    #[rstest]
1526    fn test_late_wildcard_subscription_receives_cached_topic() {
1527        let msgbus = get_message_bus();
1528        let topic = "data.instrument.POLYMARKET.TEST-SYMBOL";
1529
1530        let (early_handler, early_saver) =
1531            get_any_saving_handler::<String>(Some(Ustr::from("early")));
1532        msgbus::subscribe_any("data.*.POLYMARKET.*".into(), early_handler, None);
1533
1534        msgbus::publish_any(topic.into(), &"ONE".to_string());
1535
1536        let (late_handler, late_saver) = get_any_saving_handler::<String>(Some(Ustr::from("late")));
1537        msgbus::subscribe_any("data.instrument.POLYMARKET.*".into(), late_handler, None);
1538
1539        msgbus::publish_any(topic.into(), &"TWO".to_string());
1540
1541        assert_eq!(early_saver.get_messages(), vec!["ONE", "TWO"]);
1542        assert_eq!(late_saver.get_messages(), vec!["TWO"]);
1543
1544        let topic_mstr: MStr<Topic> = topic.into();
1545        let cached = msgbus.borrow_mut().matching_subscriptions(topic_mstr);
1546        assert_eq!(cached.len(), 2);
1547    }
1548
1549    #[rstest]
1550    fn test_late_wildcard_backfills_into_multiple_cached_topics() {
1551        let msgbus = get_message_bus();
1552        let topics = ["data.A", "data.B", "data.C"];
1553
1554        let (early_handler, early_saver) =
1555            get_any_saving_handler::<String>(Some(Ustr::from("early")));
1556        msgbus::subscribe_any("data.*".into(), early_handler, None);
1557
1558        for topic in &topics {
1559            msgbus::publish_any((*topic).into(), &(*topic).to_string());
1560        }
1561
1562        let (late_handler, late_saver) = get_any_saving_handler::<String>(Some(Ustr::from("late")));
1563        msgbus::subscribe_any("data.*".into(), late_handler, None);
1564
1565        for topic in &topics {
1566            msgbus::publish_any((*topic).into(), &format!("{topic}-2"));
1567        }
1568
1569        assert_eq!(
1570            early_saver.get_messages(),
1571            vec![
1572                "data.A", "data.B", "data.C", "data.A-2", "data.B-2", "data.C-2"
1573            ],
1574        );
1575        assert_eq!(
1576            late_saver.get_messages(),
1577            vec!["data.A-2", "data.B-2", "data.C-2"]
1578        );
1579
1580        for topic in &topics {
1581            let topic_mstr: MStr<Topic> = (*topic).into();
1582            assert_eq!(
1583                msgbus.borrow_mut().matching_subscriptions(topic_mstr).len(),
1584                2,
1585                "topic {topic} should have both subscribers cached",
1586            );
1587        }
1588    }
1589
1590    /// A simple reference model for subscription behavior.
1591    struct SimpleSubscriptionModel {
1592        /// Stores (pattern, `handler_id`) tuples for active subscriptions.
1593        subscriptions: Vec<(String, String)>,
1594    }
1595
1596    impl SimpleSubscriptionModel {
1597        fn new() -> Self {
1598            Self {
1599                subscriptions: Vec::new(),
1600            }
1601        }
1602
1603        fn subscribe(&mut self, pattern: &str, handler_id: &str) {
1604            let subscription = (pattern.to_string(), handler_id.to_string());
1605            if !self.subscriptions.contains(&subscription) {
1606                self.subscriptions.push(subscription);
1607            }
1608        }
1609
1610        fn unsubscribe(&mut self, pattern: &str, handler_id: &str) -> bool {
1611            let subscription = (pattern.to_string(), handler_id.to_string());
1612            if let Some(idx) = self.subscriptions.iter().position(|s| s == &subscription) {
1613                self.subscriptions.remove(idx);
1614                true
1615            } else {
1616                false
1617            }
1618        }
1619
1620        fn is_subscribed(&self, pattern: &str, handler_id: &str) -> bool {
1621            self.subscriptions
1622                .contains(&(pattern.to_string(), handler_id.to_string()))
1623        }
1624
1625        fn matching_subscriptions(&self, topic: &str) -> Vec<(String, String)> {
1626            let topic = topic.into();
1627
1628            self.subscriptions
1629                .iter()
1630                .filter(|(pat, _)| is_matching_backtracking(topic, pat.into()))
1631                .map(|(pat, id)| (pat.clone(), id.clone()))
1632                .collect()
1633        }
1634
1635        fn subscription_count(&self) -> usize {
1636            self.subscriptions.len()
1637        }
1638    }
1639
1640    #[rstest]
1641    fn subscription_model_fuzz_testing() {
1642        let mut rng = StdRng::seed_from_u64(42);
1643
1644        let msgbus = get_message_bus();
1645        let mut model = SimpleSubscriptionModel::new();
1646
1647        // Map from handler_id to handler
1648        let mut handlers: Vec<(String, ShareableMessageHandler)> = Vec::new();
1649
1650        // Generate some patterns
1651        let patterns = generate_test_patterns(&mut rng);
1652
1653        // Generate some handler IDs
1654        let handler_ids: Vec<String> = (0..50).map(|i| format!("handler_{i}")).collect();
1655
1656        // Initialize handlers
1657        for id in &handler_ids {
1658            let handler = get_stub_shareable_handler(Some(Ustr::from(id)));
1659            handlers.push((id.clone(), handler));
1660        }
1661
1662        let num_operations = 50_000;
1663        for op_num in 0..num_operations {
1664            let operation = rng.random_range(0..4);
1665
1666            match operation {
1667                // Subscribe
1668                0 => {
1669                    let pattern_idx = rng.random_range(0..patterns.len());
1670                    let handler_idx = rng.random_range(0..handlers.len());
1671                    let pattern = &patterns[pattern_idx];
1672                    let (handler_id, handler) = &handlers[handler_idx];
1673
1674                    // Apply to reference model
1675                    model.subscribe(pattern, handler_id);
1676
1677                    // Apply to message bus
1678                    msgbus::subscribe_any(pattern.as_str().into(), handler.clone(), None);
1679
1680                    assert_eq!(
1681                        model.subscription_count(),
1682                        msgbus.borrow().subscriptions().len()
1683                    );
1684
1685                    assert!(
1686                        msgbus.borrow().is_subscribed(pattern, handler.clone()),
1687                        "Op {op_num}: is_subscribed should return true after subscribe"
1688                    );
1689                }
1690
1691                // Unsubscribe
1692                1 => {
1693                    if model.subscription_count() > 0 {
1694                        let sub_idx = rng.random_range(0..model.subscription_count());
1695                        let (pattern, handler_id) = model.subscriptions[sub_idx].clone();
1696
1697                        // Apply to reference model
1698                        model.unsubscribe(&pattern, &handler_id);
1699
1700                        // Find handler
1701                        let handler = handlers
1702                            .iter()
1703                            .find(|(id, _)| id == &handler_id)
1704                            .map(|(_, h)| h.clone())
1705                            .unwrap();
1706
1707                        // Apply to message bus
1708                        msgbus::unsubscribe_any(pattern.as_str().into(), &handler);
1709
1710                        assert_eq!(
1711                            model.subscription_count(),
1712                            msgbus.borrow().subscriptions().len()
1713                        );
1714                        assert!(
1715                            !msgbus.borrow().is_subscribed(pattern, handler.clone()),
1716                            "Op {op_num}: is_subscribed should return false after unsubscribe"
1717                        );
1718                    }
1719                }
1720
1721                // Check is_subscribed
1722                2 => {
1723                    // Get a random pattern and handler
1724                    let pattern_idx = rng.random_range(0..patterns.len());
1725                    let handler_idx = rng.random_range(0..handlers.len());
1726                    let pattern = &patterns[pattern_idx];
1727                    let (handler_id, handler) = &handlers[handler_idx];
1728
1729                    let expected = model.is_subscribed(pattern, handler_id);
1730                    let actual = msgbus.borrow().is_subscribed(pattern, handler.clone());
1731
1732                    assert_eq!(
1733                        expected, actual,
1734                        "Op {op_num}: Subscription state mismatch for pattern '{pattern}', handler '{handler_id}': expected={expected}, actual={actual}"
1735                    );
1736                }
1737
1738                // Check matching_subscriptions
1739                3 => {
1740                    // Generate a topic
1741                    let topic = create_topic(&mut rng);
1742
1743                    let actual_matches = msgbus.borrow_mut().matching_subscriptions(topic);
1744                    let expected_matches = model.matching_subscriptions(&topic);
1745
1746                    assert_eq!(
1747                        expected_matches.len(),
1748                        actual_matches.len(),
1749                        "Op {}: Match count mismatch for topic '{}': expected={}, actual={}",
1750                        op_num,
1751                        topic,
1752                        expected_matches.len(),
1753                        actual_matches.len()
1754                    );
1755
1756                    for sub in &actual_matches {
1757                        assert!(
1758                            expected_matches
1759                                .contains(&(sub.pattern.to_string(), sub.handler_id.to_string())),
1760                            "Op {}: Expected match not found: pattern='{}', handler_id='{}'",
1761                            op_num,
1762                            sub.pattern,
1763                            sub.handler_id
1764                        );
1765                    }
1766                }
1767                _ => unreachable!(),
1768            }
1769        }
1770    }
1771
1772    fn generate_pattern_from_topic(topic: &str, rng: &mut StdRng) -> String {
1773        let mut pattern = String::new();
1774
1775        for c in topic.chars() {
1776            let val: f64 = rng.random();
1777            if val < 0.1 {
1778                pattern.push('*');
1779            } else if val < 0.3 {
1780                pattern.push('?');
1781            } else if val >= 0.5 {
1782                pattern.push(c);
1783            }
1784        }
1785
1786        pattern
1787    }
1788
1789    fn generate_test_patterns(rng: &mut StdRng) -> Vec<String> {
1790        let mut patterns = vec![
1791            "data.*.*.*".to_string(),
1792            "*.*.BINANCE.*".to_string(),
1793            "events.order.*".to_string(),
1794            "data.*.*.?USDT".to_string(),
1795            "*.trades.*.BTC*".to_string(),
1796            "*.*.*.*".to_string(),
1797        ];
1798
1799        // Add some random patterns
1800        for _ in 0..50 {
1801            match rng.random_range(0..10) {
1802                // Use existing pattern
1803                0..=1 => {
1804                    let idx = rng.random_range(0..patterns.len());
1805                    patterns.push(patterns[idx].clone());
1806                }
1807                // Generate new pattern from topic
1808                _ => {
1809                    let topic = create_topic(rng);
1810                    let pattern = generate_pattern_from_topic(&topic, rng);
1811                    patterns.push(pattern);
1812                }
1813            }
1814        }
1815
1816        patterns
1817    }
1818
1819    fn create_topic(rng: &mut StdRng) -> Ustr {
1820        let cat = ["data", "info", "order"];
1821        let model = ["quotes", "trades", "orderbooks", "depths"];
1822        let venue = ["BINANCE", "BYBIT", "OKX", "FTX", "KRAKEN"];
1823        let instrument = ["BTCUSDT", "ETHUSDT", "SOLUSDT", "XRPUSDT", "DOGEUSDT"];
1824
1825        let cat = cat[rng.random_range(0..cat.len())];
1826        let model = model[rng.random_range(0..model.len())];
1827        let venue = venue[rng.random_range(0..venue.len())];
1828        let instrument = instrument[rng.random_range(0..instrument.len())];
1829        Ustr::from(&format!("{cat}.{model}.{venue}.{instrument}"))
1830    }
1831}