1use std::{collections::HashMap, fs, path::Path, str::FromStr, sync::Arc, time::Duration};
19
20use anyhow::Context;
21use dashmap::DashMap;
22use ibapi::{
23 contracts::{ComboLegOpenClose, Contract, Exchange, LegAction, SecurityType, Symbol},
24 prelude::StreamExt,
25 subscriptions::SubscriptionItem,
26};
27use jiff::{Span, Timestamp, tz::Offset};
28use nautilus_common::{cache::Cache, config::ConfigResult};
29use nautilus_model::{
30 identifiers::{InstrumentId, Venue},
31 instruments::{Instrument, InstrumentAny},
32};
33use serde::{Deserialize, Serialize};
34
35use crate::{
36 common::{
37 Symbology,
38 contracts::{
39 ConfiguredContract, KEY_BUILD_FUTURES_CHAIN, KEY_BUILD_OPTIONS_CHAIN,
40 KEY_MAX_EXPIRY_DAYS, KEY_MIN_EXPIRY_DAYS, KEY_OPTIONS_CHAIN_EXCHANGE,
41 KEY_OPTIONS_CHAIN_EXCHANGE_ALT, parse_contract_from_json,
42 },
43 enums::{IbAction, IbSecurityType},
44 spreads::{
45 create_spread_instrument_id, is_spread_instrument_id,
46 parse_spread_instrument_id_to_legs,
47 },
48 symbology::{
49 determine_venue_from_contract, exchange_to_mic_venue, possible_exchanges_for_venue,
50 symbol_mic_venue,
51 },
52 },
53 config::{InteractiveBrokersInstrumentProviderConfig, SymbologyMethod},
54 providers::parse::{
55 expiry_timestring_to_unix_nanos, parse_ib_contract_to_instrument,
56 parse_spread_instrument_any, split_last_trade_date, trim_last_trade_date,
57 },
58};
59
60#[derive(Debug, Clone, Serialize, Deserialize)]
62struct InstrumentCache {
63 cache_timestamp: Timestamp,
65 contract_id_to_instrument_id: Vec<(i32, String)>,
67 price_magnifiers: Vec<(String, i32)>,
69 #[serde(default)]
71 contracts: Vec<(String, Contract)>,
72 #[serde(default)]
74 contract_details: Vec<(String, ibapi::contracts::ContractDetails)>,
75 instruments: Vec<(String, String)>, }
78
79#[cfg_attr(
84 feature = "python",
85 pyo3::pyclass(
86 module = "nautilus_trader.adapters.interactive_brokers",
87 unsendable,
88 from_py_object
89 )
90)]
91#[cfg_attr(
92 feature = "python",
93 pyo3_stub_gen::derive::gen_stub_pyclass(
94 module = "nautilus_trader.adapters.interactive_brokers"
95 )
96)]
97#[derive(Debug, Clone)]
98pub struct InteractiveBrokersInstrumentProvider {
99 config: InteractiveBrokersInstrumentProviderConfig,
101 symbology: Symbology,
103 contract_id_to_instrument_id: Arc<DashMap<i32, InstrumentId>>,
105 instruments: Arc<DashMap<InstrumentId, InstrumentAny>>,
107 contract_details: Arc<DashMap<InstrumentId, ibapi::contracts::ContractDetails>>,
109 contracts: Arc<DashMap<InstrumentId, Contract>>,
111 price_magnifiers: Arc<DashMap<InstrumentId, i32>>,
113 startup_initialized: Arc<tokio::sync::Mutex<bool>>,
115}
116
117trait StartupInstrumentLoader {
118 async fn load_instrument_id(
119 &self,
120 instrument_id: InstrumentId,
121 ) -> anyhow::Result<Option<InstrumentId>>;
122
123 async fn load_contract(
124 &self,
125 configured: &ConfiguredContract,
126 ) -> anyhow::Result<Vec<InstrumentId>>;
127}
128
129struct IbStartupInstrumentLoader<'a> {
130 provider: &'a InteractiveBrokersInstrumentProvider,
131 client: &'a ibapi::Client,
132}
133
134impl StartupInstrumentLoader for IbStartupInstrumentLoader<'_> {
135 async fn load_instrument_id(
136 &self,
137 instrument_id: InstrumentId,
138 ) -> anyhow::Result<Option<InstrumentId>> {
139 self.provider
140 .load_with_return_async(self.client, instrument_id, None)
141 .await
142 }
143
144 async fn load_contract(
145 &self,
146 configured: &ConfiguredContract,
147 ) -> anyhow::Result<Vec<InstrumentId>> {
148 let spec = configured.chain_spec_json();
149 self.provider
150 .load_contract_spec(self.client, &configured.contract, spec.as_ref())
151 .await
152 }
153}
154
155impl InteractiveBrokersInstrumentProvider {
156 pub fn new(config: InteractiveBrokersInstrumentProviderConfig) -> ConfigResult<Self> {
162 config.validate()?;
163
164 let symbology = Symbology::new(config.symbology_method)
165 .with_futures_year_digits(config.futures_year_digits);
166
167 Ok(Self {
168 config,
169 symbology,
170 contract_id_to_instrument_id: Arc::new(DashMap::new()),
171 instruments: Arc::new(DashMap::new()),
172 contract_details: Arc::new(DashMap::new()),
173 contracts: Arc::new(DashMap::new()),
174 price_magnifiers: Arc::new(DashMap::new()),
175 startup_initialized: Arc::new(tokio::sync::Mutex::new(false)),
176 })
177 }
178
179 #[cfg(test)]
180 pub(crate) fn insert_test_instrument(
181 &self,
182 instrument: InstrumentAny,
183 contract_id: i32,
184 price_magnifier: i32,
185 ) {
186 let instrument_id = instrument.id();
187 self.instruments.insert(instrument_id, instrument);
188 self.contract_id_to_instrument_id
189 .insert(contract_id, instrument_id);
190 self.contracts.insert(
191 instrument_id,
192 Contract {
193 contract_id,
194 ..Default::default()
195 },
196 );
197
198 self.price_magnifiers.insert(instrument_id, price_magnifier);
199 }
200
201 #[cfg(test)]
202 pub(crate) fn insert_test_contract_id_mapping(
203 &self,
204 contract_id: i32,
205 instrument_id: InstrumentId,
206 ) {
207 self.contract_id_to_instrument_id
208 .insert(contract_id, instrument_id);
209 }
210
211 pub async fn initialize(&self) -> anyhow::Result<()> {
220 self.validate()?;
221
222 if let Some(ref cache_path) = self.config.cache_path {
223 match self.load_cache(cache_path).await {
224 Ok(cache_loaded) => {
225 if cache_loaded {
226 tracing::debug!(
227 "Initialized provider with {} instruments from cache",
228 self.count()
229 );
230 } else {
231 tracing::debug!(
232 "Cache file not found or expired, starting with empty cache"
233 );
234 }
235 }
236 Err(e) => {
237 tracing::warn!("Failed to load cache during initialization: {}", e);
238 }
239 }
240 }
241
242 Ok(())
243 }
244
245 pub async fn initialize_with_client(
253 &self,
254 client: &ibapi::Client,
255 ) -> anyhow::Result<Vec<InstrumentId>> {
256 let loader = IbStartupInstrumentLoader {
257 provider: self,
258 client,
259 };
260
261 self.initialize_with_loader(&loader).await
262 }
263
264 async fn initialize_with_loader<L>(&self, loader: &L) -> anyhow::Result<Vec<InstrumentId>>
265 where
266 L: StartupInstrumentLoader + Sync,
267 {
268 let mut initialized = self.startup_initialized.lock().await;
269 if *initialized {
270 return Ok(Vec::new());
271 }
272
273 self.initialize().await?;
274 let loaded_ids = self.load_configured_instruments(loader).await?;
275 *initialized = true;
276 Ok(loaded_ids)
277 }
278
279 async fn load_configured_instruments<L>(&self, loader: &L) -> anyhow::Result<Vec<InstrumentId>>
280 where
281 L: StartupInstrumentLoader + Sync,
282 {
283 let mut loaded_ids = Vec::new();
284 let mut unresolved = Vec::new();
285 let mut configured_ids: Vec<_> = self.config.load_ids.iter().copied().collect();
286 configured_ids.sort_unstable();
287
288 for instrument_id in configured_ids {
289 match loader
290 .load_instrument_id(instrument_id)
291 .await
292 .with_context(|| {
293 format!("Failed to load configured IB instrument ID {instrument_id}")
294 })? {
295 Some(loaded_id) => loaded_ids.push(loaded_id),
296 None => unresolved.push(format!("instrument ID {instrument_id}")),
297 }
298 }
299
300 for (index, configured) in self.config.load_contracts.iter().enumerate() {
301 let contract = &configured.contract;
302
303 let mut contract_ids = loader.load_contract(configured).await.with_context(|| {
304 format!("Failed to load configured IB contract at index {index}: {contract:?}")
305 })?;
306
307 if contract_ids.is_empty() {
308 unresolved.push(format!("contract at index {index}: {contract:?}"));
309 } else {
310 loaded_ids.append(&mut contract_ids);
311 }
312 }
313
314 if !unresolved.is_empty() {
315 anyhow::bail!(
316 "Unable to resolve configured Interactive Brokers instruments: {}",
317 unresolved.join(", ")
318 );
319 }
320
321 loaded_ids.sort_unstable();
322 loaded_ids.dedup();
323 Ok(loaded_ids)
324 }
325
326 pub(crate) fn seed_from_cache(&self, cache: &Cache) -> usize {
327 let instruments = cache
328 .instrument_ids(None)
329 .into_iter()
330 .filter_map(|instrument_id| cache.instrument(instrument_id).cloned());
331 let count = self.add_cached_instruments(instruments);
332 if count > 0 {
333 tracing::debug!("Seeded IB instrument provider with {count} cached instruments");
334 }
335
336 count
337 }
338
339 pub fn add_cached_instruments<I>(&self, instruments: I) -> usize
344 where
345 I: IntoIterator<Item = InstrumentAny>,
346 {
347 let mut added = 0;
348
349 for instrument in instruments {
350 let instrument_id = instrument.id();
351
352 let Some(contract) = contract_from_instrument_info(&instrument) else {
353 continue;
354 };
355
356 let Some(price_magnifier) =
357 price_magnifier_from_instrument_info(&instrument).filter(|value| *value >= 0)
358 else {
359 continue;
360 };
361
362 if self.cache_instrument(
363 instrument_id,
364 instrument,
365 None,
366 Some(contract),
367 Some(price_magnifier),
368 false,
369 ) {
370 added += 1;
371 }
372 }
373
374 added
375 }
376
377 pub fn determine_venue(
386 &self,
387 contract: &Contract,
388 contract_details: Option<&ibapi::contracts::ContractDetails>,
389 ) -> Venue {
390 if matches!(contract.security_type, SecurityType::Stock) {
391 if let Some(venue) = symbol_mic_venue(contract, &self.config.symbol_to_mic_venue) {
392 return Venue::from(venue.as_str());
393 }
394 return Venue::from(self.resolve_stock_exchange_from_contract(contract).as_str());
395 }
396
397 let valid_exchanges = contract_details.map(|details| details.valid_exchanges.join(","));
398 let venue_str = determine_venue_from_contract(
399 contract,
400 &self.config.symbol_to_mic_venue,
401 self.config.convert_exchange_to_mic_venue,
402 valid_exchanges.as_deref(),
403 );
404 Venue::from(venue_str.as_str())
405 }
406
407 fn resolve_stock_exchange_from_contract(&self, contract: &Contract) -> String {
408 let cached_venue = self.resolve_cached_symbol_venue(contract);
409 if let Some(venue) = cached_venue.as_deref()
410 && Self::is_compatible_cached_stock_venue(venue, contract.primary_exchange.as_str())
411 {
412 return venue.to_string();
413 }
414
415 if !contract.primary_exchange.as_str().is_empty()
416 && contract.primary_exchange.as_str() != "SMART"
417 {
418 return if self.config.convert_exchange_to_mic_venue {
419 exchange_to_mic_venue(contract.primary_exchange.as_str())
420 .unwrap_or_else(|| contract.primary_exchange.as_str().to_string())
421 } else {
422 contract.primary_exchange.as_str().to_string()
423 };
424 }
425
426 if contract.exchange.as_str() == "SMART"
427 && let Some(venue) = cached_venue
428 {
429 return venue;
430 }
431
432 let exchange = contract.exchange.as_str();
433 if self.config.convert_exchange_to_mic_venue {
434 exchange_to_mic_venue(exchange).unwrap_or_else(|| exchange.to_string())
435 } else {
436 exchange.to_string()
437 }
438 }
439
440 fn is_compatible_cached_stock_venue(venue: &str, primary_exchange: &str) -> bool {
441 if primary_exchange.is_empty() || primary_exchange == "SMART" {
442 return true;
443 }
444
445 venue == primary_exchange
446 || exchange_to_mic_venue(primary_exchange).is_some_and(|mic| mic == venue)
447 }
448
449 fn resolve_cached_symbol_venue(&self, contract: &Contract) -> Option<String> {
450 self.instruments.iter().find_map(|entry| {
451 let instrument = entry.value();
452 let instrument_id = instrument.id();
453 (instrument_id.symbol.as_str() == contract.symbol.as_str())
454 .then(|| instrument_id.venue.to_string())
455 })
456 }
457
458 pub fn symbology_method(&self) -> SymbologyMethod {
460 self.symbology.method()
461 }
462
463 #[must_use]
469 pub fn find(&self, instrument_id: &InstrumentId) -> Option<InstrumentAny> {
470 self.instruments
471 .get(instrument_id)
472 .map(|entry| entry.value().clone())
473 }
474
475 #[must_use]
476 pub(crate) fn find_all(&self, instrument_ids: &[InstrumentId]) -> Vec<InstrumentAny> {
477 instrument_ids
478 .iter()
479 .filter_map(|instrument_id| self.find(instrument_id))
480 .collect()
481 }
482
483 #[must_use]
489 pub fn find_by_contract_id(&self, contract_id: i32) -> Option<InstrumentAny> {
490 self.get_instrument_id_by_contract_id(contract_id)
491 .and_then(|instrument_id| self.find(&instrument_id))
492 }
493
494 #[must_use]
500 pub fn get_instrument_id_by_contract_id(&self, contract_id: i32) -> Option<InstrumentId> {
501 self.contract_id_to_instrument_id
502 .get(&contract_id)
503 .map(|entry| *entry.value())
504 }
505
506 pub fn resolve_instrument_id_for_contract(
515 &self,
516 contract: &Contract,
517 ) -> anyhow::Result<InstrumentId> {
518 if contract.contract_id != 0
519 && let Some(instrument_id) = self.get_instrument_id_by_contract_id(contract.contract_id)
520 {
521 return Ok(instrument_id);
522 }
523
524 if contract.security_type == SecurityType::Spread {
525 return self.resolve_spread_instrument_id_for_contract(contract);
526 }
527
528 let venue = self.determine_venue(contract, None);
529
530 self.symbology.instrument_id(contract, Some(venue))
531 }
532
533 fn resolve_spread_instrument_id_for_contract(
534 &self,
535 contract: &Contract,
536 ) -> anyhow::Result<InstrumentId> {
537 let spread_instrument_id = self.spread_instrument_id_for_contract(contract)?;
538
539 if self.find(&spread_instrument_id).is_none() {
540 anyhow::bail!("Resolved BAG spread {spread_instrument_id} is not cached");
541 }
542
543 Ok(spread_instrument_id)
544 }
545
546 pub fn spread_instrument_id_for_contract(
553 &self,
554 contract: &Contract,
555 ) -> anyhow::Result<InstrumentId> {
556 if contract.combo_legs.is_empty() {
557 anyhow::bail!("Cannot resolve BAG contract without combo legs or cached contract ID");
558 }
559
560 let mut leg_tuples = Vec::with_capacity(contract.combo_legs.len());
561
562 for combo_leg in &contract.combo_legs {
563 let leg_instrument_id = self
564 .get_instrument_id_by_contract_id(combo_leg.contract_id)
565 .with_context(|| {
566 format!(
567 "Cannot resolve BAG leg con_id {} to cached instrument ID",
568 combo_leg.contract_id
569 )
570 })?;
571
572 let ratio = IbAction::from_str(combo_leg.action.as_str())
573 .context("Invalid BAG combo leg action")?
574 .signed_multiplier()
575 * combo_leg.ratio;
576
577 leg_tuples.push((leg_instrument_id, ratio));
578 }
579
580 create_spread_instrument_id(&leg_tuples)
581 .context("Failed to create spread instrument ID from BAG combo legs")
582 }
583
584 #[must_use]
590 pub fn is_filtered_sec_type(&self, sec_type: &str) -> bool {
591 IbSecurityType::from_str(sec_type)
592 .is_ok_and(|sec_type| self.config.filter_sec_types.contains(&sec_type))
593 }
594
595 #[must_use]
601 pub fn get_all(&self) -> Vec<InstrumentAny> {
602 self.instruments
603 .iter()
604 .map(|entry| entry.value().clone())
605 .collect()
606 }
607
608 #[must_use]
614 pub fn count(&self) -> usize {
615 self.instruments.len()
616 }
617
618 #[must_use]
631 pub fn get_price_magnifier(&self, instrument_id: &InstrumentId) -> i32 {
632 if let Some(magnifier) = self.price_magnifier(instrument_id) {
633 return magnifier;
634 }
635
636 if self.instruments.contains_key(instrument_id) {
638 tracing::debug!(
639 "Price magnifier not found for instrument {} (has instrument but no contract details), using default 1",
640 instrument_id
641 );
642 } else {
643 tracing::trace!(
644 "Price magnifier not found for instrument {} (instrument not loaded), using default 1",
645 instrument_id
646 );
647 }
648
649 1
651 }
652
653 #[must_use]
656 pub fn price_magnifier(&self, instrument_id: &InstrumentId) -> Option<i32> {
657 if let Some(magnifier) = self.price_magnifiers.get(instrument_id) {
658 return Some(normalize_price_magnifier(*magnifier.value()));
659 }
660
661 let magnifier = normalize_price_magnifier(
662 self.contract_details
663 .get(instrument_id)?
664 .value()
665 .price_magnifier,
666 );
667 self.price_magnifiers.insert(*instrument_id, magnifier);
668 Some(magnifier)
669 }
670
671 pub(crate) fn seed_price_magnifier_from_cache(
678 &self,
679 cache: &Cache,
680 instrument_id: &InstrumentId,
681 ) -> Option<i32> {
682 if let Some(magnifier) = self.price_magnifier(instrument_id) {
683 return Some(magnifier);
684 }
685
686 if let Some(instrument) = cache.instrument(instrument_id) {
687 self.add_cached_instruments([instrument.clone()]);
688 }
689
690 self.price_magnifier(instrument_id)
691 }
692
693 pub async fn ensure_price_magnifier_async(
701 &self,
702 client: &ibapi::Client,
703 instrument_id: InstrumentId,
704 timeout: Duration,
705 ) -> anyhow::Result<i32> {
706 self.ensure_price_magnifier_with(instrument_id, timeout, || async {
707 if is_spread_instrument_id(&instrument_id) {
708 self.fetch_spread_instrument(client, instrument_id, true, None)
709 .await
710 .map(|_| ())
711 } else {
712 self.fetch_contract_details(client, instrument_id, true, None)
713 .await
714 }
715 })
716 .await
717 }
718
719 async fn ensure_price_magnifier_with<F, Fut>(
720 &self,
721 instrument_id: InstrumentId,
722 timeout: Duration,
723 load: F,
724 ) -> anyhow::Result<i32>
725 where
726 F: FnOnce() -> Fut,
727 Fut: std::future::Future<Output = anyhow::Result<()>>,
728 {
729 if let Some(magnifier) = self.price_magnifier(&instrument_id) {
730 return Ok(magnifier);
731 }
732
733 tokio::time::timeout(timeout, load())
736 .await
737 .map_err(|_| {
738 anyhow::anyhow!(
739 "Timed out after {timeout:?} loading IB contract details for {instrument_id}"
740 )
741 })?
742 .with_context(|| format!("Failed to load IB contract details for {instrument_id}"))?;
743
744 self.price_magnifier(&instrument_id).with_context(|| {
745 format!("IB price magnifier for {instrument_id} is unknown: no contract details loaded")
746 })
747 }
748
749 pub async fn get_instrument(
762 &self,
763 client: &ibapi::Client,
764 contract: &Contract,
765 ) -> anyhow::Result<Option<InstrumentAny>> {
766 log::debug!(
767 "IB get_instrument request sec_type={:?} con_id={} symbol={} local_symbol={} exchange={} expiry={}",
768 contract.security_type,
769 contract.contract_id,
770 contract.symbol.as_str(),
771 contract.local_symbol.as_str(),
772 contract.exchange.as_str(),
773 contract.last_trade_date_or_contract_month.as_str()
774 );
775 let sec_type_str = contract.security_type.to_string();
777 if self.is_filtered_sec_type(&sec_type_str) {
778 tracing::debug!(
779 "Skipping filtered security type {} for contract",
780 sec_type_str
781 );
782 return Ok(None);
783 }
784
785 let contract_id = contract.contract_id;
786
787 if let Some(cached_instrument_id) = self.contract_id_to_instrument_id.get(&contract_id) {
789 log::debug!(
790 "IB get_instrument cache hit for contract_id={} -> {}",
791 contract_id,
792 cached_instrument_id.value()
793 );
794
795 if let Some(instrument) = self.find(cached_instrument_id.value()) {
796 return Ok(Some(instrument));
797 }
798 }
799
800 if contract.security_type == SecurityType::Spread && !contract.combo_legs.is_empty() {
802 self.fetch_bag_contract(client, contract).await?;
804
805 if let Some(spread_instrument_id) = self.contract_id_to_instrument_id.get(&contract_id)
807 {
808 return Ok(self.find(spread_instrument_id.value()));
809 }
810
811 if let Ok(spread_instrument_id) =
812 self.resolve_spread_instrument_id_for_contract(contract)
813 {
814 return Ok(self.find(&spread_instrument_id));
815 }
816 }
817
818 let details_vec = request_contract_details(client, contract)
820 .await
821 .context("Failed to fetch contract details from IB")?;
822
823 log::debug!(
824 "IB get_instrument received {} contract details for sec_type={:?} symbol={} local_symbol={}",
825 details_vec.len(),
826 contract.security_type,
827 contract.symbol.as_str(),
828 contract.local_symbol.as_str()
829 );
830
831 if details_vec.is_empty() {
832 tracing::warn!("No contract details returned for contract {}", contract_id);
833 return Ok(None);
834 }
835
836 let loaded_ids = self.process_contract_details(details_vec, None, false);
837
838 if contract_id != 0
839 && let Some(instrument) = self.find_by_contract_id(contract_id)
840 {
841 return Ok(Some(instrument));
842 }
843
844 Ok(loaded_ids
845 .first()
846 .and_then(|instrument_id| self.find(instrument_id)))
847 }
848
849 pub(crate) async fn load_contract_spec(
850 &self,
851 client: &ibapi::Client,
852 contract: &Contract,
853 spec: Option<&serde_json::Value>,
854 ) -> anyhow::Result<Vec<InstrumentId>> {
855 let mut loaded_ids = Vec::new();
856 let build_futures_chain = json_opt_bool(spec, KEY_BUILD_FUTURES_CHAIN)
857 .or(self.config.build_futures_chain)
858 .unwrap_or(false);
859 let build_options_chain = json_opt_bool(spec, KEY_BUILD_OPTIONS_CHAIN)
860 .or(self.config.build_options_chain)
861 .unwrap_or(false);
862 let min_expiry_days = json_u32(spec, KEY_MIN_EXPIRY_DAYS).or(self.config.min_expiry_days);
863 let max_expiry_days = json_u32(spec, KEY_MAX_EXPIRY_DAYS).or(self.config.max_expiry_days);
864 let options_chain_exchange = json_string(spec, KEY_OPTIONS_CHAIN_EXCHANGE)
865 .or_else(|| json_string(spec, KEY_OPTIONS_CHAIN_EXCHANGE_ALT));
866
867 let chain_contract = if contract.security_type == SecurityType::ContinuousFuture
868 && (build_futures_chain || build_options_chain)
869 {
870 match request_contract_details(client, contract).await {
871 Ok(details_vec) => details_vec
872 .into_iter()
873 .next().map_or_else(|| contract.clone(), |details| {
874 tracing::debug!(
875 "Qualified continuous future contract {}.{} as local_symbol={} trading_class={} con_id={}",
876 contract.symbol.as_str(),
877 contract.exchange.as_str(),
878 details.contract.local_symbol.as_str(),
879 details.contract.trading_class.as_str(),
880 details.contract.contract_id,
881 );
882 details.contract
883 }),
884 Err(e) if e.is_connection_lost() => {
885 return Err(e).context("Failed to qualify continuous future contract");
886 }
887 Err(e) => {
888 tracing::warn!(
889 "Failed to qualify continuous future contract {:?}: {}",
890 contract,
891 e
892 );
893 contract.clone()
894 }
895 }
896 } else {
897 contract.clone()
898 };
899
900 let chain_trading_class = (!chain_contract.trading_class.is_empty())
901 .then_some(chain_contract.trading_class.as_str());
902
903 if build_futures_chain {
904 let loaded = self
905 .fetch_futures_chain(
906 client,
907 chain_contract.symbol.as_str(),
908 chain_contract.exchange.as_str(),
909 chain_contract.currency.as_str(),
910 chain_trading_class,
911 contract.security_type == SecurityType::ContinuousFuture,
912 min_expiry_days,
913 max_expiry_days,
914 )
915 .await?;
916 tracing::debug!(
917 "Loaded {} futures instruments for chain request {}.{}",
918 loaded,
919 chain_contract.symbol.as_str(),
920 chain_contract.exchange.as_str(),
921 );
922 loaded_ids.extend(self.cached_contract_ids_for(
923 chain_contract.symbol.as_str(),
924 chain_contract.exchange.as_str(),
925 &[SecurityType::Future],
926 ));
927 }
928
929 if build_options_chain {
930 let expiry_min = expiry_bound_from_days(min_expiry_days);
931 let expiry_max = expiry_bound_from_days(max_expiry_days);
932 let options_exchange = options_chain_exchange
935 .as_deref()
936 .unwrap_or_else(|| contract.exchange.as_str());
937 let mut underlyings = Vec::new();
938
939 if contract.security_type == SecurityType::ContinuousFuture {
940 self.fetch_futures_chain(
943 client,
944 chain_contract.symbol.as_str(),
945 chain_contract.exchange.as_str(),
946 chain_contract.currency.as_str(),
947 chain_trading_class,
948 true,
949 Some(0),
950 Some(u32::MAX),
951 )
952 .await?;
953
954 underlyings.extend(
955 self.cached_contracts_for(
956 contract.symbol.as_str(),
957 chain_contract.exchange.as_str(),
958 &[SecurityType::Future],
959 )
960 .into_iter()
961 .map(|(_, contract)| contract),
962 );
963 } else if let Some(instrument) = self.get_instrument(client, contract).await? {
964 let instrument_id = instrument.id();
965 loaded_ids.push(instrument_id);
966 if let Some(underlying) = self.instrument_id_to_ib_contract(&instrument_id) {
967 underlyings.push(underlying);
968 }
969 }
970
971 for underlying in underlyings {
972 let loaded = self
973 .fetch_option_chain_by_range(
974 client,
975 &underlying,
976 expiry_min.as_deref(),
977 expiry_max.as_deref(),
978 Some(options_exchange),
979 )
980 .await?;
981 tracing::debug!(
982 "Loaded {} option instruments for chain request {}.{}",
983 loaded,
984 underlying.symbol.as_str(),
985 underlying.exchange.as_str(),
986 );
987 }
988
989 loaded_ids.extend(self.cached_contract_ids_for(
990 contract.symbol.as_str(),
991 options_exchange,
992 &[SecurityType::Option, SecurityType::FuturesOption],
993 ));
994 }
995
996 if !build_futures_chain
997 && !build_options_chain
998 && let Some(instrument) = self.get_instrument(client, contract).await?
999 {
1000 loaded_ids.push(instrument.id());
1001 }
1002
1003 loaded_ids.sort_unstable();
1004 loaded_ids.dedup();
1005 Ok(loaded_ids)
1006 }
1007
1008 fn cached_contract_ids_for(
1009 &self,
1010 symbol: &str,
1011 exchange: &str,
1012 security_types: &[SecurityType],
1013 ) -> Vec<InstrumentId> {
1014 self.cached_contracts_for(symbol, exchange, security_types)
1015 .into_iter()
1016 .map(|(instrument_id, _)| instrument_id)
1017 .collect()
1018 }
1019
1020 fn cached_contracts_for(
1021 &self,
1022 symbol: &str,
1023 exchange: &str,
1024 security_types: &[SecurityType],
1025 ) -> Vec<(InstrumentId, Contract)> {
1026 self.contracts
1027 .iter()
1028 .filter_map(|entry| {
1029 let instrument_id = *entry.key();
1030 let contract = entry.value();
1031 let exchange_matches =
1032 exchange.is_empty() || contract.exchange.as_str() == exchange;
1033 if contract.symbol.as_str() == symbol
1034 && exchange_matches
1035 && security_types.contains(&contract.security_type)
1036 {
1037 Some((instrument_id, contract.clone()))
1038 } else {
1039 None
1040 }
1041 })
1042 .collect()
1043 }
1044
1045 #[must_use]
1053 pub fn instrument_id_to_ib_contract_details(
1054 &self,
1055 instrument_id: &InstrumentId,
1056 ) -> Option<ibapi::contracts::ContractDetails> {
1057 self.contract_details
1058 .get(instrument_id)
1059 .map(|entry| entry.value().clone())
1060 }
1061
1062 #[must_use]
1063 pub fn instrument_id_to_ib_contract(&self, instrument_id: &InstrumentId) -> Option<Contract> {
1064 self.contracts
1065 .get(instrument_id)
1066 .map(|entry| entry.value().clone())
1067 }
1068
1069 pub fn resolve_contract_for_instrument(
1070 &self,
1071 instrument_id: InstrumentId,
1072 ) -> anyhow::Result<Contract> {
1073 let cached_contract = self.instrument_id_to_ib_contract(&instrument_id);
1074 if let Some(contract) = cached_contract.as_ref()
1075 && (contract.contract_id != 0 || is_spread_instrument_id(&instrument_id))
1076 {
1077 return Ok(contract.clone());
1078 }
1079
1080 if let Some(details) = self.instrument_id_to_ib_contract_details(&instrument_id) {
1081 return Ok(details.contract);
1082 }
1083
1084 if let Some(contract) = cached_contract {
1085 return Ok(contract);
1086 }
1087
1088 let currency = self
1089 .instruments
1090 .get(&instrument_id)
1091 .map(|instrument| instrument.quote_currency().code.to_string());
1092 self.symbology
1093 .contract_with_currency(instrument_id, None, currency.as_deref())
1094 }
1095
1096 pub async fn resolve_contract_for_instrument_async(
1097 &self,
1098 client: &ibapi::Client,
1099 instrument_id: InstrumentId,
1100 ) -> anyhow::Result<Contract> {
1101 if let Ok(contract) = self.resolve_contract_for_instrument(instrument_id)
1102 && (contract.contract_id != 0 || self.contract_details.contains_key(&instrument_id))
1103 {
1104 return Ok(contract);
1105 }
1106
1107 if is_spread_instrument_id(&instrument_id) {
1108 self.fetch_spread_instrument(client, instrument_id, false, None)
1109 .await?;
1110 } else {
1111 self.fetch_contract_details(client, instrument_id, false, None)
1112 .await?;
1113 }
1114
1115 self.resolve_contract_for_instrument(instrument_id)
1116 }
1117
1118 pub async fn load_with_return_async(
1130 &self,
1131 client: &ibapi::Client,
1132 instrument_id: InstrumentId,
1133 filters: Option<HashMap<String, String>>,
1134 ) -> anyhow::Result<Option<InstrumentId>> {
1135 let filters: Option<HashMap<String, String>> = filters;
1136 let force_instrument_update = filters
1137 .as_ref()
1138 .and_then(|f| f.get("force_instrument_update"))
1139 .is_some_and(|v| v == "true");
1140
1141 if is_spread_instrument_id(&instrument_id) {
1142 self.fetch_spread_instrument(client, instrument_id, force_instrument_update, filters)
1143 .await?;
1144 } else {
1145 self.fetch_contract_details(client, instrument_id, force_instrument_update, filters)
1146 .await?;
1147 }
1148
1149 if self.instruments.contains_key(&instrument_id) {
1150 Ok(Some(instrument_id))
1151 } else {
1152 Ok(None)
1153 }
1154 }
1155
1156 pub async fn load_ids_with_return_async(
1168 &self,
1169 client: &ibapi::Client,
1170 instrument_ids: Vec<InstrumentId>,
1171 filters: Option<HashMap<String, String>>,
1172 ) -> anyhow::Result<Vec<InstrumentId>> {
1173 let mut loaded_ids = Vec::new();
1174
1175 for instrument_id in instrument_ids {
1176 match self
1177 .load_with_return_async(client, instrument_id, filters.clone())
1178 .await
1179 {
1180 Ok(Some(loaded_id)) => loaded_ids.push(loaded_id),
1181 Ok(None) => {}
1182 Err(e) => {
1183 tracing::warn!("Failed to load instrument {}: {}", instrument_id, e);
1184 }
1185 }
1186 }
1187
1188 Ok(loaded_ids)
1189 }
1190
1191 fn create_bag_contract_from_legs(
1192 &self,
1193 leg_contract_details: &[(ibapi::contracts::ContractDetails, i32)],
1194 instrument_id: Option<InstrumentId>,
1195 bag_contract: Option<&Contract>,
1196 ) -> anyhow::Result<Contract> {
1197 if let Some(bag_contract) = bag_contract {
1198 return Ok(bag_contract.clone());
1199 }
1200
1201 let (first_details, _) = leg_contract_details
1202 .first()
1203 .ok_or_else(|| anyhow::anyhow!("Cannot create BAG contract without leg details"))?;
1204
1205 let combo_legs = leg_contract_details
1206 .iter()
1207 .map(|(details, ratio)| ibapi::contracts::ComboLeg {
1208 contract_id: details.contract.contract_id,
1209 ratio: ratio.abs(),
1210 action: if *ratio > 0 {
1211 LegAction::Buy
1212 } else {
1213 LegAction::Sell
1214 },
1215 exchange: details.contract.exchange.to_string(),
1216 open_close: ComboLegOpenClose::Same,
1217 short_sale_slot: 0,
1218 designated_location: String::new(),
1219 exempt_code: -1,
1220 })
1221 .collect();
1222
1223 Ok(Contract {
1224 symbol: first_details.contract.symbol.clone(),
1225 security_type: SecurityType::Spread,
1226 exchange: Exchange::from("SMART"),
1227 currency: first_details.contract.currency.clone(),
1228 local_symbol: instrument_id.map_or_else(String::new, |id| id.symbol.to_string()),
1229 combo_legs_description: instrument_id.map_or_else(
1230 || "Spread".to_string(),
1231 |id| format!("Spread: {}", id.symbol),
1232 ),
1233 combo_legs,
1234 ..Default::default()
1235 })
1236 }
1237
1238 pub async fn fetch_spread_instrument(
1252 &self,
1253 client: &ibapi::Client,
1254 spread_instrument_id: InstrumentId,
1255 force_instrument_update: bool,
1256 filters: Option<HashMap<String, String>>,
1257 ) -> anyhow::Result<bool> {
1258 if !force_instrument_update && self.instruments.contains_key(&spread_instrument_id) {
1260 tracing::debug!("Spread instrument {} already cached", spread_instrument_id);
1261 return Ok(true);
1262 }
1263
1264 let leg_tuples = parse_spread_instrument_id_to_legs(&spread_instrument_id)
1266 .context("Failed to parse spread instrument ID to leg tuples")?;
1267
1268 if leg_tuples.is_empty() {
1269 tracing::error!("Spread instrument {} has no legs", spread_instrument_id);
1270 return Ok(false);
1271 }
1272
1273 tracing::debug!(
1274 "Loading spread instrument {} with {} legs",
1275 spread_instrument_id,
1276 leg_tuples.len()
1277 );
1278
1279 let mut leg_contract_details = Vec::new();
1281
1282 for (leg_instrument_id, ratio) in &leg_tuples {
1283 tracing::debug!(
1284 "Loading leg instrument: {} (ratio: {})",
1285 leg_instrument_id,
1286 ratio
1287 );
1288
1289 self.fetch_contract_details(
1291 client,
1292 *leg_instrument_id,
1293 force_instrument_update,
1294 filters.clone(),
1295 )
1296 .await
1297 .with_context(|| format!("Failed to load leg instrument: {leg_instrument_id}"))?;
1298
1299 let leg_details = self
1301 .contract_details
1302 .get(leg_instrument_id)
1303 .map(|entry| entry.value().clone())
1304 .ok_or_else(|| {
1305 anyhow::anyhow!(
1306 "Leg instrument {leg_instrument_id} not found in contract details after loading"
1307 )
1308 })?;
1309
1310 leg_contract_details.push((leg_details, *ratio));
1311 }
1312
1313 let timestamp = nautilus_core::time::get_atomic_clock_realtime().get_time_ns();
1315 let leg_details_refs: Vec<(&ibapi::contracts::ContractDetails, i32)> =
1316 leg_contract_details.iter().map(|(d, r)| (d, *r)).collect();
1317
1318 let bag_contract = self.create_bag_contract_from_legs(
1319 &leg_contract_details,
1320 Some(spread_instrument_id),
1321 None,
1322 )?;
1323 let spread_instrument = parse_spread_instrument_any(
1324 spread_instrument_id,
1325 &leg_details_refs,
1326 Some(&bag_contract),
1327 Some(timestamp),
1328 )
1329 .context("Failed to parse spread instrument")?;
1330
1331 self.instruments
1333 .insert(spread_instrument_id, spread_instrument);
1334 self.contracts.insert(spread_instrument_id, bag_contract);
1335
1336 if let Some((first_details, _)) = leg_contract_details.first() {
1337 self.price_magnifiers
1338 .insert(spread_instrument_id, first_details.price_magnifier);
1339 }
1340
1341 tracing::debug!(
1342 "Successfully loaded spread instrument {}",
1343 spread_instrument_id
1344 );
1345 Ok(true)
1346 }
1347
1348 pub async fn load_all_async(
1358 &self,
1359 client: &ibapi::Client,
1360 instrument_ids: Option<Vec<InstrumentId>>,
1361 contracts: Option<Vec<Contract>>,
1362 force_instrument_update: bool,
1363 ) -> anyhow::Result<Vec<InstrumentId>> {
1364 self.validate()?;
1365 let mut loaded_ids = Vec::new();
1366
1367 let ids_to_load =
1369 instrument_ids.unwrap_or_else(|| self.config.load_ids.iter().copied().collect());
1370
1371 if !ids_to_load.is_empty() {
1372 let mut filters = std::collections::HashMap::new();
1373 if force_instrument_update {
1374 filters.insert("force_instrument_update".to_string(), "true".to_string());
1375 }
1376
1377 let filters = if filters.is_empty() {
1378 None
1379 } else {
1380 Some(filters)
1381 };
1382
1383 let ids_result = self
1384 .load_ids_with_return_async(client, ids_to_load, filters)
1385 .await
1386 .context("Failed to load instruments from IDs")?;
1387 loaded_ids.extend(ids_result);
1388 }
1389
1390 if let Some(contracts_to_load) = contracts {
1392 for contract in contracts_to_load {
1393 match self.load_contract_spec(client, &contract, None).await {
1394 Ok(mut instrument_ids) => {
1395 loaded_ids.append(&mut instrument_ids);
1396 }
1397 Err(e) => {
1398 tracing::warn!(
1399 "Error loading instrument from contract {:?}: {}",
1400 contract,
1401 e
1402 );
1403 }
1404 }
1405 }
1406 } else {
1407 for configured in &self.config.load_contracts {
1408 let spec = configured.chain_spec_json();
1409
1410 match self
1411 .load_contract_spec(client, &configured.contract, spec.as_ref())
1412 .await
1413 {
1414 Ok(mut instrument_ids) => {
1415 loaded_ids.append(&mut instrument_ids);
1416 }
1417 Err(e) => {
1418 tracing::warn!(
1419 "Error loading instrument from contract {:?}: {}",
1420 configured.contract,
1421 e
1422 );
1423 }
1424 }
1425 }
1426 }
1427
1428 if loaded_ids.is_empty() {
1429 tracing::debug!("load_all_async called but no instruments were loaded");
1430 } else {
1431 tracing::debug!("load_all_async loaded {} instruments", loaded_ids.len());
1432 }
1433
1434 Ok(loaded_ids)
1435 }
1436
1437 fn validate(&self) -> ConfigResult<()> {
1438 self.config.validate()
1439 }
1440}
1441
1442fn normalize_price_magnifier(price_magnifier: i32) -> i32 {
1443 if price_magnifier > 0 {
1444 price_magnifier
1445 } else {
1446 1
1447 }
1448}
1449
1450async fn request_contract_details(
1453 client: &ibapi::Client,
1454 contract: &Contract,
1455) -> Result<Vec<ibapi::contracts::ContractDetails>, ibapi::Error> {
1456 let mut details_vec = client.contract_details(contract).await?;
1457 details_vec.iter_mut().for_each(split_last_trade_date);
1458 Ok(details_vec)
1459}
1460
1461fn json_opt_bool(spec: Option<&serde_json::Value>, key: &str) -> Option<bool> {
1462 spec.and_then(|value| value.get(key))
1463 .and_then(serde_json::Value::as_bool)
1464}
1465
1466fn json_u32(spec: Option<&serde_json::Value>, key: &str) -> Option<u32> {
1467 spec.and_then(|value| value.get(key))
1468 .and_then(serde_json::Value::as_u64)
1469 .and_then(|value| u32::try_from(value).ok())
1470}
1471
1472fn json_string(spec: Option<&serde_json::Value>, key: &str) -> Option<String> {
1473 spec.and_then(|value| value.get(key))
1474 .and_then(serde_json::Value::as_str)
1475 .filter(|value| !value.is_empty())
1476 .map(ToString::to_string)
1477}
1478
1479fn contract_from_instrument_info(instrument: &InstrumentAny) -> Option<Contract> {
1480 let value = serde_json::to_value(instrument).ok()?;
1481 let contract_json = find_contract_json(&value)?;
1482 let mut contract = parse_contract_from_json(contract_json).ok()?;
1483 trim_last_trade_date(&mut contract);
1485 Some(contract)
1486}
1487
1488fn price_magnifier_from_instrument_info(instrument: &InstrumentAny) -> Option<i32> {
1489 let value = serde_json::to_value(instrument).ok()?;
1490 let price_magnifier = find_price_magnifier_json(&value)?;
1491 parse_i32_json(price_magnifier)
1492}
1493
1494fn find_contract_json(value: &serde_json::Value) -> Option<&serde_json::Value> {
1495 if let Some(contract_json) = value.get("info").and_then(|info| info.get("contract")) {
1496 return Some(contract_json);
1497 }
1498
1499 value.as_object()?.values().find_map(find_contract_json)
1500}
1501
1502fn find_price_magnifier_json(value: &serde_json::Value) -> Option<&serde_json::Value> {
1503 if let Some(info) = value.get("info")
1504 && let Some(price_magnifier) = info
1505 .get("priceMagnifier")
1506 .or_else(|| info.get("price_magnifier"))
1507 {
1508 return Some(price_magnifier);
1509 }
1510
1511 value
1512 .as_object()?
1513 .values()
1514 .find_map(find_price_magnifier_json)
1515}
1516
1517fn parse_i32_json(value: &serde_json::Value) -> Option<i32> {
1518 if let Some(value) = value.as_i64() {
1519 return i32::try_from(value).ok();
1520 }
1521
1522 if let Some(value) = value.as_u64() {
1523 return i32::try_from(value).ok();
1524 }
1525
1526 value.as_str()?.parse::<i32>().ok()
1527}
1528
1529fn expiry_bound_from_days(days: Option<u32>) -> Option<String> {
1530 days.map(|days| {
1531 Offset::UTC
1532 .to_datetime(Timestamp::now())
1533 .date()
1534 .checked_add(Span::new().days(i64::from(days)))
1535 .expect("expiry bound date in range")
1536 .strftime("%Y%m%d")
1537 .to_string()
1538 })
1539}
1540
1541impl InteractiveBrokersInstrumentProvider {
1542 pub async fn fetch_contract_details(
1548 &self,
1549 client: &ibapi::Client,
1550 instrument_id: InstrumentId,
1551 force_instrument_update: bool,
1552 filters: Option<HashMap<String, String>>,
1553 ) -> anyhow::Result<()> {
1554 if !force_instrument_update
1555 && self.instruments.contains_key(&instrument_id)
1556 && (self.contract_details.contains_key(&instrument_id)
1557 || self.contracts.contains_key(&instrument_id))
1558 {
1559 tracing::debug!(
1560 "Instrument {} already cached, skipping fetch",
1561 instrument_id
1562 );
1563 return Ok(());
1564 }
1565
1566 let exchange = filters
1568 .as_ref()
1569 .and_then(|f| f.get("exchange"))
1570 .map(|s| s.as_str());
1571
1572 let exchanges_to_try: Vec<String> = if let Some(exchange) = exchange {
1573 vec![exchange.to_string()]
1574 } else {
1575 possible_exchanges_for_venue(instrument_id.venue.as_str())
1576 };
1577
1578 let mut details_vec = Vec::new();
1579 let mut last_error = None;
1580
1581 for candidate_exchange in exchanges_to_try {
1582 let contract = self
1583 .symbology
1584 .contract(instrument_id, Some(candidate_exchange.as_str()))
1585 .with_context(|| format!("Failed to convert instrument_id {instrument_id} to IB contract. Check that the instrument ID format is correct and the venue/symbol are valid."))?;
1586
1587 match request_contract_details(client, &contract).await {
1588 Ok(result) if !result.is_empty() => {
1589 details_vec = result;
1590 break;
1591 }
1592 Ok(_) => {}
1593 Err(e) => {
1594 last_error = Some((candidate_exchange.clone(), e));
1595 }
1596 }
1597 }
1598
1599 if details_vec.is_empty() {
1600 if let Some((candidate_exchange, e)) = last_error {
1601 return Err(e).with_context(|| {
1602 format!(
1603 "Failed to fetch contract details for {instrument_id} on {candidate_exchange}"
1604 )
1605 });
1606 } else {
1607 tracing::warn!(
1608 "No contract details returned for {} - instrument may not exist in IB or contract specification is incomplete",
1609 instrument_id
1610 );
1611 }
1612
1613 return Ok(());
1614 }
1615
1616 let loaded_ids = self.process_contract_details(
1617 details_vec,
1618 Some(instrument_id.venue),
1619 force_instrument_update,
1620 );
1621
1622 if loaded_ids.is_empty() {
1623 tracing::warn!("No contract details were processed for {}", instrument_id);
1624 } else {
1625 tracing::debug!(
1626 "Successfully loaded {} instrument(s) for {}",
1627 loaded_ids.len(),
1628 instrument_id
1629 );
1630 }
1631
1632 Ok(())
1633 }
1634
1635 fn process_contract_details(
1636 &self,
1637 details_vec: Vec<ibapi::contracts::ContractDetails>,
1638 venue: Option<Venue>,
1639 force_instrument_update: bool,
1640 ) -> Vec<InstrumentId> {
1641 let mut processed_ids = Vec::new();
1642
1643 for details in details_vec {
1644 match self.process_contract_detail(&details, venue, force_instrument_update) {
1645 Ok(Some(instrument_id)) => processed_ids.push(instrument_id),
1646 Ok(None) => {}
1647 Err(e) => {
1648 tracing::warn!(
1649 "Failed to process IB contract details con_id={} sec_type={}: {}",
1650 details.contract.contract_id,
1651 details.contract.security_type,
1652 e
1653 );
1654 }
1655 }
1656 }
1657
1658 processed_ids
1659 }
1660
1661 fn process_contract_detail(
1662 &self,
1663 details: &ibapi::contracts::ContractDetails,
1664 venue: Option<Venue>,
1665 force_instrument_update: bool,
1666 ) -> anyhow::Result<Option<InstrumentId>> {
1667 let sec_type = details.contract.security_type.to_string();
1668 if self.is_filtered_sec_type(&sec_type) {
1669 tracing::debug!(
1670 "Skipping filtered security type {} for contract {:?}",
1671 sec_type,
1672 details.contract
1673 );
1674 return Ok(None);
1675 }
1676
1677 let resolved_venue =
1678 venue.unwrap_or_else(|| self.determine_venue(&details.contract, Some(details)));
1679 let instrument_id = self
1680 .instrument_id_from_contract(&details.contract, resolved_venue)
1681 .context("Failed to convert IB contract to instrument ID")?;
1682
1683 let instrument = match parse_ib_contract_to_instrument(details, instrument_id) {
1684 Ok(instrument) => instrument,
1685 Err(e) => {
1686 tracing::warn!(
1687 "Failed to parse IB contract details for {}: {}",
1688 instrument_id,
1689 e
1690 );
1691 return Ok(None);
1692 }
1693 };
1694
1695 if !self.passes_filter_callable(&instrument)? {
1696 return Ok(None);
1697 }
1698
1699 self.cache_instrument(
1700 instrument_id,
1701 instrument,
1702 Some(details.clone()),
1703 None,
1704 None,
1705 force_instrument_update,
1706 );
1707
1708 Ok(Some(instrument_id))
1709 }
1710
1711 pub(crate) fn instrument_id_from_contract(
1712 &self,
1713 contract: &Contract,
1714 venue: Venue,
1715 ) -> anyhow::Result<InstrumentId> {
1716 self.symbology.instrument_id(contract, Some(venue))
1717 }
1718
1719 fn cache_instrument(
1720 &self,
1721 instrument_id: InstrumentId,
1722 instrument: InstrumentAny,
1723 details: Option<ibapi::contracts::ContractDetails>,
1724 contract: Option<Contract>,
1725 price_magnifier: Option<i32>,
1726 force_instrument_update: bool,
1727 ) -> bool {
1728 let should_update =
1729 force_instrument_update || !self.instruments.contains_key(&instrument_id);
1730 if should_update {
1731 self.instruments.insert(instrument_id, instrument);
1732 }
1733
1734 if let Some(details) = details {
1735 let contract_id = details.contract.contract_id;
1736 self.contracts
1737 .insert(instrument_id, details.contract.clone());
1738 self.contract_details.insert(instrument_id, details.clone());
1739
1740 if contract_id != 0 {
1741 self.contract_id_to_instrument_id
1742 .insert(contract_id, instrument_id);
1743 }
1744
1745 self.price_magnifiers.insert(
1746 instrument_id,
1747 normalize_price_magnifier(details.price_magnifier),
1748 );
1749 } else if let Some(contract) = contract {
1750 if contract.contract_id != 0 {
1751 self.contract_id_to_instrument_id
1752 .insert(contract.contract_id, instrument_id);
1753 }
1754
1755 self.contracts.insert(instrument_id, contract);
1756 }
1757
1758 if let Some(price_magnifier) = price_magnifier {
1759 self.price_magnifiers
1760 .insert(instrument_id, normalize_price_magnifier(price_magnifier));
1761 }
1762
1763 should_update
1764 }
1765
1766 fn passes_filter_callable(&self, instrument: &InstrumentAny) -> anyhow::Result<bool> {
1767 let Some(filter_callable) = self.config.filter_callable.as_deref() else {
1768 return Ok(true);
1769 };
1770
1771 #[cfg(feature = "python")]
1772 {
1773 use nautilus_model::python::instruments::instrument_any_to_pyobject;
1774 use pyo3::{prelude::*, types::PyModule};
1775
1776 Python::attach(|py| {
1777 let (module_name, callable_name) =
1778 filter_callable.rsplit_once('.').ok_or_else(|| {
1779 anyhow::anyhow!(
1780 "Invalid filter_callable path {filter_callable:?}; expected module.callable"
1781 )
1782 })?;
1783
1784 let callable = PyModule::import(py, module_name)
1785 .map_err(|e| anyhow::anyhow!("Failed to import {module_name}: {e}"))?
1786 .getattr(callable_name)
1787 .map_err(|e| anyhow::anyhow!("Failed to resolve {filter_callable}: {e}"))?;
1788 let py_instrument = instrument_any_to_pyobject(py, instrument.clone())
1789 .map_err(|e| anyhow::anyhow!("Failed to convert instrument to Python: {e}"))?;
1790 callable
1791 .call1((py_instrument,))
1792 .and_then(|result| result.extract::<bool>())
1793 .map_err(|e| anyhow::anyhow!("filter_callable {filter_callable} failed: {e}"))
1794 })
1795 }
1796
1797 #[cfg(not(feature = "python"))]
1798 {
1799 let _ = instrument;
1800 anyhow::bail!(
1801 "filter_callable {filter_callable:?} requires the Interactive Brokers adapter to be built with the python feature"
1802 );
1803 }
1804 }
1805
1806 pub async fn batch_load(
1818 &self,
1819 client: &ibapi::Client,
1820 instrument_ids: Vec<InstrumentId>,
1821 filters: Option<&[String]>,
1822 ) -> anyhow::Result<Vec<InstrumentId>> {
1823 let mut loaded_ids = Vec::new();
1824
1825 let filtered_ids: Vec<InstrumentId> = if let Some(filter_list) = filters {
1827 instrument_ids
1833 .into_iter()
1834 .filter(|instrument_id| {
1835 for filter in filter_list {
1837 if instrument_id
1839 .symbol
1840 .as_str()
1841 .to_lowercase()
1842 .contains(&filter.to_lowercase())
1843 {
1844 return true;
1845 }
1846
1847 if instrument_id.venue.as_str() == filter {
1849 return true;
1850 }
1851
1852 if let Some(contract_details) = self.contract_details.get(instrument_id) {
1854 let sec_type_str = contract_details.contract.security_type.to_string();
1855
1856 if sec_type_str.to_uppercase().contains(&filter.to_uppercase()) {
1857 return true;
1858 }
1859 }
1860 }
1861
1862 false
1863 })
1864 .collect()
1865 } else {
1866 instrument_ids
1867 };
1868
1869 let filtered_count = filtered_ids.len();
1871 for instrument_id in filtered_ids {
1872 match self
1873 .fetch_contract_details(client, instrument_id, false, None)
1874 .await
1875 {
1876 Ok(()) => loaded_ids.push(instrument_id),
1877 Err(e) => {
1878 tracing::warn!("Failed to load instrument {}: {}", instrument_id, e);
1879 }
1880 }
1881 }
1882
1883 tracing::debug!(
1884 "Batch loaded {} instruments ({} after filtering)",
1885 loaded_ids.len(),
1886 filtered_count
1887 );
1888
1889 if !loaded_ids.is_empty()
1891 && let Some(ref cache_path) = self.config.cache_path
1892 && let Err(e) = self.save_cache(cache_path).await
1893 {
1894 tracing::warn!("Failed to save instrument cache to {}: {}", cache_path, e);
1895 }
1896
1897 Ok(loaded_ids)
1898 }
1899
1900 pub async fn fetch_option_chain_by_range(
1914 &self,
1915 client: &ibapi::Client,
1916 underlying: &Contract,
1917 expiry_min: Option<&str>,
1918 expiry_max: Option<&str>,
1919 option_chain_exchange: Option<&str>,
1920 ) -> anyhow::Result<usize> {
1921 let exchange = option_chain_exchange.unwrap_or_else(|| underlying.exchange.as_str());
1922 tracing::debug!(
1923 "Building option chain for {}.{} (sec_type={:?}, contract_id={}, expiry_min={:?}, expiry_max={:?}, config_min_days={:?}, config_max_days={:?})",
1924 underlying.symbol.as_str(),
1925 exchange,
1926 underlying.security_type,
1927 underlying.contract_id,
1928 expiry_min,
1929 expiry_max,
1930 self.config.min_expiry_days,
1931 self.config.max_expiry_days,
1932 );
1933
1934 let symbol = underlying.symbol.as_str();
1936 let mut option_chain_request = client.option_chain(
1937 symbol,
1938 underlying.security_type.clone(),
1939 underlying.contract_id,
1940 );
1941
1942 if underlying.security_type == SecurityType::Future {
1945 option_chain_request = option_chain_request.exchange(exchange);
1946 }
1947
1948 let mut option_chain_stream = option_chain_request
1949 .subscribe()
1950 .await
1951 .context("Failed to request option chain from IB")?;
1952
1953 let mut total_loaded = 0;
1954
1955 let now = nautilus_core::time::get_atomic_clock_realtime().get_time_ns();
1957
1958 let mut all_expirations = Vec::new();
1960
1961 while let Some(result) = option_chain_stream.next().await {
1962 match result {
1963 Ok(SubscriptionItem::Data(chain)) => {
1964 tracing::debug!(
1965 "Received option chain metadata exchange={} trading_class={} expirations={} strikes={}",
1966 chain.exchange,
1967 chain.trading_class,
1968 chain.expirations.len(),
1969 chain.strikes.len(),
1970 );
1971
1972 if chain.exchange != exchange {
1973 continue;
1974 }
1975
1976 for expiration in &chain.expirations {
1977 let date_filter_pass = match (expiry_min, expiry_max) {
1979 (Some(min), Some(max)) => {
1980 expiration.as_str() >= min && expiration.as_str() <= max
1981 }
1982 (Some(min), None) => expiration.as_str() >= min,
1983 (None, Some(max)) => expiration.as_str() <= max,
1984 (None, None) => true,
1985 };
1986
1987 let days_filter_pass = {
1989 let expiry_ns =
1990 expiry_timestring_to_unix_nanos(expiration.as_str(), None)
1991 .unwrap_or(now);
1992 let days_until_expiry =
1993 (expiry_ns.as_u64().saturating_sub(now.as_u64()))
1994 / (24 * 60 * 60 * 1_000_000_000);
1995
1996 let min_days_ok = self
1997 .config
1998 .min_expiry_days
1999 .is_none_or(|min| days_until_expiry >= min as u64);
2000 let max_days_ok = self
2001 .config
2002 .max_expiry_days
2003 .is_none_or(|max| days_until_expiry <= max as u64);
2004
2005 min_days_ok && max_days_ok
2006 };
2007
2008 if date_filter_pass
2009 && days_filter_pass
2010 && !all_expirations.contains(expiration)
2011 {
2012 all_expirations.push(expiration.clone());
2013 }
2014 }
2015 }
2016 Ok(SubscriptionItem::Notice(notice)) => {
2017 tracing::debug!("Received option chain notice: {notice:?}");
2018 }
2019 Err(e) => {
2020 tracing::warn!("Error receiving option chain metadata: {e}");
2021 }
2022 }
2023 }
2024
2025 all_expirations.sort_unstable();
2026
2027 tracing::debug!(
2028 "Filtered {} option expirations for {}.{}",
2029 all_expirations.len(),
2030 underlying.symbol.as_str(),
2031 exchange,
2032 );
2033
2034 for expiration in all_expirations {
2036 tracing::debug!(
2037 "Requesting option contract details for {}.{} expiry {}",
2038 underlying.symbol.as_str(),
2039 exchange,
2040 expiration,
2041 );
2042
2043 let option_contract = Contract {
2044 contract_id: 0,
2045 symbol: underlying.symbol.clone(),
2046 security_type: if underlying.security_type == SecurityType::Future {
2047 SecurityType::FuturesOption
2048 } else {
2049 SecurityType::Option
2050 },
2051 last_trade_date_or_contract_month: expiration.clone(),
2052 strike: f64::MAX,
2053 right: None,
2054 multiplier: String::new(),
2055 exchange: Exchange::from(exchange),
2056 currency: underlying.currency.clone(),
2057 local_symbol: String::new(),
2058 primary_exchange: Exchange::from(""),
2059 trading_class: String::new(),
2060 include_expired: false,
2061 security_id_type: None,
2062 security_id: String::new(),
2063 combo_legs_description: String::new(),
2064 combo_legs: Vec::new(),
2065 delta_neutral_contract: None,
2066 issuer_id: String::new(),
2067 description: String::new(),
2068 last_trade_date: None,
2069 };
2070
2071 match request_contract_details(client, &option_contract).await {
2072 Ok(details_vec) => {
2073 tracing::debug!(
2074 "Received {} raw option contract details for {}.{} expiry {}",
2075 details_vec.len(),
2076 underlying.symbol.as_str(),
2077 exchange,
2078 expiration,
2079 );
2080
2081 for details in details_vec {
2082 if details.under_contract_id != underlying.contract_id {
2084 continue;
2085 }
2086
2087 let contract_id = details.contract.contract_id;
2088
2089 if self.contract_id_to_instrument_id.contains_key(&contract_id) {
2090 continue;
2091 }
2092
2093 match self.process_contract_detail(&details, None, false) {
2094 Ok(Some(_instrument_id)) => {
2095 total_loaded += 1;
2096 }
2097 Ok(None) => {}
2098 Err(e) => {
2099 tracing::warn!("Failed to parse option instrument: {}", e);
2100 }
2101 }
2102 }
2103 }
2104 Err(e) => {
2105 tracing::warn!(
2106 "Failed to fetch contract details for expiration {}: {}",
2107 expiration,
2108 e
2109 );
2110 }
2111 }
2112 }
2113
2114 tracing::debug!(
2115 "Successfully loaded {} option instruments from chain for {}.{}",
2116 total_loaded,
2117 underlying.symbol.as_str(),
2118 exchange,
2119 );
2120
2121 if total_loaded > 0
2123 && let Some(ref cache_path) = self.config.cache_path
2124 && let Err(e) = self.save_cache(cache_path).await
2125 {
2126 tracing::warn!("Failed to save instrument cache to {}: {}", cache_path, e);
2127 }
2128
2129 Ok(total_loaded)
2130 }
2131
2132 #[allow(clippy::too_many_arguments)] pub async fn fetch_futures_chain(
2146 &self,
2147 client: &ibapi::Client,
2148 symbol: &str,
2149 exchange: &str,
2150 currency: &str,
2151 trading_class: Option<&str>,
2152 include_expired: bool,
2153 min_expiry_days: Option<u32>,
2154 max_expiry_days: Option<u32>,
2155 ) -> anyhow::Result<usize> {
2156 tracing::debug!(
2157 "Building futures chain for {}.{} (currency={}, trading_class={:?}, include_expired={}, min_days={:?}, max_days={:?}, config_min_days={:?}, config_max_days={:?})",
2158 symbol,
2159 exchange,
2160 currency,
2161 trading_class,
2162 include_expired,
2163 min_expiry_days,
2164 max_expiry_days,
2165 self.config.min_expiry_days,
2166 self.config.max_expiry_days,
2167 );
2168
2169 let futures_contract = Contract {
2171 contract_id: 0,
2172 symbol: Symbol::from(symbol.to_string()),
2173 security_type: SecurityType::Future,
2174 last_trade_date_or_contract_month: String::new(),
2175 strike: f64::MAX,
2176 right: None,
2177 multiplier: String::new(),
2178 exchange: Exchange::from(exchange.to_string()),
2179 currency: ibapi::contracts::Currency::from(currency.to_string()),
2180 local_symbol: String::new(),
2181 primary_exchange: Exchange::from(""),
2182 trading_class: trading_class.unwrap_or_default().to_string(),
2183 include_expired,
2184 security_id_type: None,
2185 security_id: String::new(),
2186 combo_legs_description: String::new(),
2187 combo_legs: Vec::new(),
2188 delta_neutral_contract: None,
2189 issuer_id: String::new(),
2190 description: String::new(),
2191 last_trade_date: None,
2192 };
2193
2194 let details_vec = request_contract_details(client, &futures_contract)
2196 .await
2197 .context("Failed to fetch futures chain from IB")?;
2198
2199 tracing::debug!(
2200 "Received {} raw futures contract details for {}.{}",
2201 details_vec.len(),
2202 symbol,
2203 exchange,
2204 );
2205
2206 let mut total_loaded = 0;
2207 let now = nautilus_core::time::get_atomic_clock_realtime().get_time_ns();
2208
2209 for details in details_vec {
2210 let contract_id = details.contract.contract_id;
2211
2212 if self.contract_id_to_instrument_id.contains_key(&contract_id) {
2214 continue;
2215 }
2216
2217 let sec_type_str = details.contract.security_type.to_string();
2219 if self.is_filtered_sec_type(&sec_type_str) {
2220 continue;
2221 }
2222
2223 if !details
2225 .contract
2226 .last_trade_date_or_contract_month
2227 .is_empty()
2228 && let Ok(expiry_ns) = expiry_timestring_to_unix_nanos(
2229 &details.contract.last_trade_date_or_contract_month,
2230 Some(&details),
2231 )
2232 {
2233 let days_until_expiry = (expiry_ns.as_u64().saturating_sub(now.as_u64()))
2234 / (24 * 60 * 60 * 1_000_000_000);
2235
2236 let min_days_ok = min_expiry_days
2237 .or(self.config.min_expiry_days)
2238 .is_none_or(|min| days_until_expiry >= min as u64);
2239 let max_days_ok = max_expiry_days
2240 .or(self.config.max_expiry_days)
2241 .is_none_or(|max| days_until_expiry <= max as u64);
2242
2243 if !min_days_ok || !max_days_ok {
2244 continue;
2245 }
2246 }
2247
2248 match self.process_contract_detail(&details, None, false) {
2249 Ok(Some(_instrument_id)) => {
2250 total_loaded += 1;
2251 }
2252 Ok(None) => {}
2253 Err(e) => {
2254 tracing::warn!("Failed to parse futures instrument: {}", e);
2255 }
2256 }
2257 }
2258
2259 tracing::debug!(
2260 "Successfully loaded {} futures instruments from chain",
2261 total_loaded
2262 );
2263
2264 if total_loaded > 0
2266 && let Some(ref cache_path) = self.config.cache_path
2267 && let Err(e) = self.save_cache(cache_path).await
2268 {
2269 tracing::warn!("Failed to save instrument cache to {}: {}", cache_path, e);
2270 }
2271
2272 Ok(total_loaded)
2273 }
2274
2275 pub async fn fetch_bag_contract(
2294 &self,
2295 client: &ibapi::Client,
2296 bag_contract: &Contract,
2297 ) -> anyhow::Result<usize> {
2298 if bag_contract.security_type != SecurityType::Spread || bag_contract.combo_legs.is_empty()
2300 {
2301 anyhow::bail!(
2302 "Invalid BAG contract: must have security_type=Spread and non-empty combo_legs"
2303 );
2304 }
2305
2306 tracing::debug!(
2307 "Loading BAG contract with {} legs",
2308 bag_contract.combo_legs.len()
2309 );
2310
2311 let mut leg_contract_details = Vec::new();
2313 let mut leg_tuples = Vec::new();
2314
2315 for combo_leg in &bag_contract.combo_legs {
2316 let leg_contract = Contract {
2318 contract_id: combo_leg.contract_id, symbol: bag_contract.symbol.clone(), security_type: SecurityType::Option, last_trade_date_or_contract_month: String::new(),
2322 strike: 0.0,
2323 right: None,
2324 multiplier: String::new(),
2325 exchange: Exchange::from(combo_leg.exchange.as_str()),
2326 currency: bag_contract.currency.clone(), local_symbol: String::new(),
2328 primary_exchange: Exchange::default(),
2329 trading_class: String::new(),
2330 include_expired: false,
2331 security_id_type: None,
2332 security_id: String::new(),
2333 combo_legs_description: String::new(),
2334 combo_legs: Vec::new(),
2335 delta_neutral_contract: None,
2336 issuer_id: String::new(),
2337 description: String::new(),
2338 last_trade_date: None,
2339 };
2340
2341 let leg_details_vec = request_contract_details(client, &leg_contract)
2343 .await
2344 .with_context(|| {
2345 format!(
2346 "Failed to fetch contract details for leg conId {}",
2347 combo_leg.contract_id
2348 )
2349 })?;
2350
2351 if leg_details_vec.is_empty() {
2352 tracing::warn!(
2353 "No contract details returned for leg conId {}",
2354 combo_leg.contract_id
2355 );
2356 continue;
2357 }
2358
2359 let leg_details = &leg_details_vec[0];
2360 let leg_contract_id = leg_details.contract.contract_id;
2361
2362 let leg_instrument_id =
2364 if let Some(cached_id) = self.contract_id_to_instrument_id.get(&leg_contract_id) {
2365 *cached_id.value()
2366 } else {
2367 let leg_venue = self.determine_venue(&leg_details.contract, Some(leg_details));
2369 let leg_instrument_id = self
2370 .symbology
2371 .instrument_id(&leg_details.contract, Some(leg_venue))
2372 .context("Failed to convert leg contract to instrument ID")?;
2373
2374 let leg_instrument =
2376 parse_ib_contract_to_instrument(leg_details, leg_instrument_id)
2377 .context("Failed to parse leg instrument")?;
2378
2379 self.instruments.insert(leg_instrument_id, leg_instrument);
2380 self.contract_details
2381 .insert(leg_instrument_id, leg_details.clone());
2382 self.contracts
2383 .insert(leg_instrument_id, leg_details.contract.clone());
2384 self.contract_id_to_instrument_id
2385 .insert(leg_contract_id, leg_instrument_id);
2386 self.price_magnifiers
2387 .insert(leg_instrument_id, leg_details.price_magnifier);
2388
2389 leg_instrument_id
2390 };
2391
2392 let ratio = IbAction::from_str(combo_leg.action.as_str())
2394 .context("Invalid combo leg action")?
2395 .signed_multiplier()
2396 * combo_leg.ratio;
2397
2398 let leg_details_clone = self
2400 .contract_details
2401 .get(&leg_instrument_id)
2402 .map(|entry| entry.value().clone())
2403 .ok_or_else(|| {
2404 anyhow::anyhow!(
2405 "Contract details not found for leg {leg_instrument_id} after loading"
2406 )
2407 })?;
2408
2409 leg_contract_details.push((leg_details_clone, ratio));
2410 leg_tuples.push((leg_instrument_id, ratio));
2411 }
2412
2413 if leg_tuples.is_empty() {
2414 anyhow::bail!("No valid legs loaded for BAG contract");
2415 }
2416
2417 let spread_instrument_id = create_spread_instrument_id(&leg_tuples)
2419 .context("Failed to create spread instrument ID from leg tuples")?;
2420
2421 let bag_details_vec = request_contract_details(client, bag_contract)
2423 .await
2424 .context("Failed to fetch BAG contract details from IB")?;
2425
2426 if bag_details_vec.is_empty() {
2427 tracing::warn!("No contract details returned for BAG contract");
2428
2429 if bag_contract.contract_id != 0 && self.instruments.contains_key(&spread_instrument_id)
2430 {
2431 self.contract_id_to_instrument_id
2432 .insert(bag_contract.contract_id, spread_instrument_id);
2433 }
2434
2435 return Ok(0);
2436 }
2437
2438 let bag_details = &bag_details_vec[0];
2439 let bag_contract_id = bag_details.contract.contract_id;
2440
2441 if bag_contract_id != 0 {
2442 self.contract_id_to_instrument_id
2443 .insert(bag_contract_id, spread_instrument_id);
2444 }
2445
2446 if self.instruments.contains_key(&spread_instrument_id) {
2448 tracing::debug!("Spread instrument {} already cached", spread_instrument_id);
2449 self.contract_details
2450 .insert(spread_instrument_id, bag_details.clone());
2451 self.contracts
2452 .insert(spread_instrument_id, bag_details.contract.clone());
2453 self.price_magnifiers
2454 .insert(spread_instrument_id, bag_details.price_magnifier);
2455 return Ok(0);
2456 }
2457
2458 let timestamp = nautilus_core::time::get_atomic_clock_realtime().get_time_ns();
2460
2461 let leg_details_refs: Vec<(&ibapi::contracts::ContractDetails, i32)> =
2463 leg_contract_details.iter().map(|(d, r)| (d, *r)).collect();
2464
2465 let spread_instrument = parse_spread_instrument_any(
2466 spread_instrument_id,
2467 &leg_details_refs,
2468 Some(&bag_details.contract),
2469 Some(timestamp),
2470 )
2471 .context("Failed to parse spread instrument")?;
2472
2473 self.instruments
2475 .insert(spread_instrument_id, spread_instrument);
2476 self.contract_details
2477 .insert(spread_instrument_id, bag_details.clone());
2478 self.contracts
2479 .insert(spread_instrument_id, bag_details.contract.clone());
2480 self.price_magnifiers
2481 .insert(spread_instrument_id, bag_details.price_magnifier);
2482
2483 tracing::debug!(
2484 "Successfully loaded spread instrument {} with {} legs",
2485 spread_instrument_id,
2486 leg_tuples.len()
2487 );
2488
2489 if let Some(ref cache_path) = self.config.cache_path
2491 && let Err(e) = self.save_cache(cache_path).await
2492 {
2493 tracing::warn!("Failed to save instrument cache to {}: {}", cache_path, e);
2494 }
2495
2496 Ok(1)
2497 }
2498
2499 pub async fn save_cache(&self, cache_path: &str) -> anyhow::Result<()> {
2505 let cache = InstrumentCache {
2506 cache_timestamp: Timestamp::now(),
2507 contract_id_to_instrument_id: self
2508 .contract_id_to_instrument_id
2509 .iter()
2510 .map(|entry| (*entry.key(), entry.value().to_string()))
2511 .collect(),
2512 price_magnifiers: self
2513 .price_magnifiers
2514 .iter()
2515 .map(|entry| (entry.key().to_string(), *entry.value()))
2516 .collect(),
2517 contracts: self
2518 .contracts
2519 .iter()
2520 .map(|entry| (entry.key().to_string(), entry.value().clone()))
2521 .collect(),
2522 contract_details: self
2523 .contract_details
2524 .iter()
2525 .map(|entry| (entry.key().to_string(), entry.value().clone()))
2526 .collect(),
2527 instruments: self
2528 .instruments
2529 .iter()
2530 .map(|entry| {
2531 let instrument_id = entry.key().to_string();
2532 let json =
2533 serde_json::to_string(entry.value()).unwrap_or_else(|_| String::new());
2534 (instrument_id, json)
2535 })
2536 .collect(),
2537 };
2538
2539 if let Some(parent) = Path::new(cache_path).parent() {
2541 fs::create_dir_all(parent)?;
2542 }
2543
2544 let json = serde_json::to_string_pretty(&cache)?;
2546 fs::write(cache_path, json)?;
2547 tracing::debug!(
2548 "Saved instrument cache to {} ({} instruments)",
2549 cache_path,
2550 cache.instruments.len()
2551 );
2552 Ok(())
2553 }
2554
2555 pub async fn load_cache(&self, cache_path: &str) -> anyhow::Result<bool> {
2565 if !Path::new(cache_path).exists() {
2567 tracing::debug!("Cache file does not exist: {}", cache_path);
2568 return Ok(false);
2569 }
2570
2571 let json = fs::read_to_string(cache_path)?;
2573 let cache: InstrumentCache = serde_json::from_str(&json)?;
2574
2575 if let Some(validity_days) = self.config.cache_validity_days {
2577 let cache_age = cache.cache_timestamp.duration_until(Timestamp::now());
2578 let max_age = jiff::SignedDuration::from_hours(24 * (validity_days as i64));
2579 if cache_age > max_age {
2580 tracing::debug!(
2581 "Cache is expired (age: {} days, max: {} days). Ignoring cache",
2582 cache_age.as_secs() / (24 * 60 * 60),
2583 validity_days
2584 );
2585 return Ok(false);
2586 }
2587 }
2588
2589 let mut loaded_count = 0;
2591
2592 for (instrument_id_str, instrument_json) in &cache.instruments {
2593 match InstrumentId::from_str(instrument_id_str) {
2594 Ok(instrument_id) => match serde_json::from_str::<InstrumentAny>(instrument_json) {
2595 Ok(instrument) => {
2596 self.instruments.insert(instrument_id, instrument);
2597
2598 if let Ok(value) =
2599 serde_json::from_str::<serde_json::Value>(instrument_json)
2600 && let Some(contract_json) = find_contract_json(&value)
2601 && let Ok(mut contract) = parse_contract_from_json(contract_json)
2602 {
2603 trim_last_trade_date(&mut contract);
2604
2605 if contract.contract_id != 0 {
2606 self.contract_id_to_instrument_id
2607 .insert(contract.contract_id, instrument_id);
2608 }
2609
2610 self.contracts.insert(instrument_id, contract);
2611 }
2612
2613 loaded_count += 1;
2614 }
2615 Err(e) => {
2616 tracing::warn!(
2617 "Failed to deserialize instrument {}: {}",
2618 instrument_id_str,
2619 e
2620 );
2621 }
2622 },
2623 Err(e) => {
2624 tracing::warn!("Failed to parse instrument ID {}: {}", instrument_id_str, e);
2625 }
2626 }
2627 }
2628
2629 for (instrument_id_str, contract) in &cache.contracts {
2632 if let Ok(instrument_id) = InstrumentId::from_str(instrument_id_str) {
2633 if contract.contract_id != 0 {
2634 self.contract_id_to_instrument_id
2635 .insert(contract.contract_id, instrument_id);
2636 }
2637
2638 let mut contract = contract.clone();
2639 trim_last_trade_date(&mut contract);
2640 self.contracts.insert(instrument_id, contract);
2641 }
2642 }
2643
2644 for (instrument_id_str, details) in &cache.contract_details {
2645 if let Ok(instrument_id) = InstrumentId::from_str(instrument_id_str) {
2646 if details.contract.contract_id != 0 {
2647 self.contract_id_to_instrument_id
2648 .insert(details.contract.contract_id, instrument_id);
2649 }
2650
2651 let mut details = details.clone();
2652 split_last_trade_date(&mut details);
2653 self.contracts
2654 .insert(instrument_id, details.contract.clone());
2655 self.contract_details.insert(instrument_id, details);
2656 }
2657 }
2658
2659 for (contract_id, instrument_id_str) in &cache.contract_id_to_instrument_id {
2661 if let Ok(instrument_id) = InstrumentId::from_str(instrument_id_str) {
2662 self.contract_id_to_instrument_id
2663 .insert(*contract_id, instrument_id);
2664 }
2665 }
2666
2667 for (instrument_id_str, magnifier) in &cache.price_magnifiers {
2669 if let Ok(instrument_id) = InstrumentId::from_str(instrument_id_str) {
2670 self.price_magnifiers.insert(instrument_id, *magnifier);
2671 }
2672 }
2673
2674 tracing::debug!(
2675 "Loaded instrument cache from {} ({} instruments, created at {})",
2676 cache_path,
2677 loaded_count,
2678 cache.cache_timestamp
2679 );
2680 Ok(true)
2681 }
2682}
2683
2684#[cfg(test)]
2685mod tests {
2686 use std::{
2687 fs,
2688 sync::atomic::{AtomicBool, AtomicUsize, Ordering},
2689 };
2690
2691 use indexmap::IndexMap;
2692 use nautilus_common::config::ConfigError;
2693 use nautilus_core::{Params, UnixNanos};
2694 use nautilus_model::{
2695 identifiers::{Symbol, Venue},
2696 instruments::CurrencyPair,
2697 types::{Price, Quantity, currency::Currency},
2698 };
2699 use rstest::rstest;
2700 use tempfile::TempDir;
2701
2702 use super::*;
2703 use crate::common::contract_to_json_value;
2704
2705 struct TestStartupLoader {
2706 id_calls: AtomicUsize,
2707 contract_calls: AtomicUsize,
2708 fail_next_id: AtomicBool,
2709 resolve_ids: AtomicBool,
2710 resolve_contracts: AtomicBool,
2711 yield_on_load: bool,
2712 }
2713
2714 impl TestStartupLoader {
2715 fn new(resolve_ids: bool, resolve_contracts: bool) -> Self {
2716 Self {
2717 id_calls: AtomicUsize::new(0),
2718 contract_calls: AtomicUsize::new(0),
2719 fail_next_id: AtomicBool::new(false),
2720 resolve_ids: AtomicBool::new(resolve_ids),
2721 resolve_contracts: AtomicBool::new(resolve_contracts),
2722 yield_on_load: false,
2723 }
2724 }
2725 }
2726
2727 impl StartupInstrumentLoader for TestStartupLoader {
2728 async fn load_instrument_id(
2729 &self,
2730 instrument_id: InstrumentId,
2731 ) -> anyhow::Result<Option<InstrumentId>> {
2732 self.id_calls.fetch_add(1, Ordering::SeqCst);
2733
2734 if self.yield_on_load {
2735 tokio::task::yield_now().await;
2736 }
2737
2738 if self.fail_next_id.swap(false, Ordering::SeqCst) {
2739 anyhow::bail!("Socket disconnected");
2740 }
2741
2742 Ok(self
2743 .resolve_ids
2744 .load(Ordering::SeqCst)
2745 .then_some(instrument_id))
2746 }
2747
2748 async fn load_contract(
2749 &self,
2750 _configured: &ConfiguredContract,
2751 ) -> anyhow::Result<Vec<InstrumentId>> {
2752 self.contract_calls.fetch_add(1, Ordering::SeqCst);
2753
2754 if self.yield_on_load {
2755 tokio::task::yield_now().await;
2756 }
2757
2758 Ok(if self.resolve_contracts.load(Ordering::SeqCst) {
2759 vec![InstrumentId::new(
2760 Symbol::from("MSFT"),
2761 Venue::from("NASDAQ"),
2762 )]
2763 } else {
2764 Vec::new()
2765 })
2766 }
2767 }
2768
2769 fn create_test_provider_with_cache() -> (InteractiveBrokersInstrumentProvider, TempDir) {
2770 let temp_dir = TempDir::new().unwrap();
2771 let cache_path = temp_dir
2772 .path()
2773 .join("test_cache.json")
2774 .to_str()
2775 .unwrap()
2776 .to_string();
2777
2778 let config = InteractiveBrokersInstrumentProviderConfig::builder()
2779 .cache_path(cache_path)
2780 .cache_validity_days(7u32)
2781 .build();
2782
2783 let provider = InteractiveBrokersInstrumentProvider::new(config).unwrap();
2784 (provider, temp_dir)
2785 }
2786
2787 fn opra_option_contract_details(mut contract: Contract) -> ibapi::contracts::ContractDetails {
2788 contract.contract_id = 12_345;
2789 contract.symbol = ibapi::contracts::Symbol::from("AAPL");
2790 contract.security_type = SecurityType::Option;
2791 contract.exchange = Exchange::from("SMART");
2792 contract.currency = ibapi::contracts::Currency::from("USD");
2793 contract.local_symbol = "AAPL 270115P00155000".to_string();
2794 contract.last_trade_date_or_contract_month = "20270115".to_string();
2795 contract.strike = 155.0;
2796 contract.right = Some(ibapi::contracts::OptionRight::Put);
2797 contract.multiplier = "100".to_string();
2798
2799 ibapi::contracts::ContractDetails {
2800 contract,
2801 min_tick: 0.01,
2802 under_symbol: "AAPL".to_string(),
2803 under_security_type: "STK".to_string(),
2804 valid_exchanges: vec!["SMART".to_string(), "CBOE".to_string()],
2805 ..Default::default()
2806 }
2807 }
2808
2809 fn create_test_instrument(instrument_id: InstrumentId) -> InstrumentAny {
2810 create_test_instrument_with_info(instrument_id, None)
2811 }
2812
2813 #[rstest]
2814 fn test_qualified_opra_details_preserve_canonical_instrument_identity() {
2815 let provider = InteractiveBrokersInstrumentProvider::new(Default::default()).unwrap();
2816 let requested_id = InstrumentId::from("AAPL 270115P00155000.OPRA");
2817 let request = provider
2818 .resolve_contract_for_instrument(requested_id)
2819 .unwrap();
2820
2821 assert_eq!(request.security_type, SecurityType::Option);
2822 assert_eq!(request.exchange.as_str(), "SMART");
2823 assert!(request.symbol.as_str().is_empty());
2824 assert_eq!(request.currency.as_str(), "USD");
2825 assert_eq!(request.local_symbol, "AAPL 270115P00155000");
2826 assert!(request.last_trade_date_or_contract_month.is_empty());
2827 assert!(request.right.is_none());
2828 assert_eq!(request.strike, 0.0);
2829
2830 let details = opra_option_contract_details(request);
2831 let loaded_id = provider
2832 .process_contract_detail(&details, Some(requested_id.venue), false)
2833 .unwrap()
2834 .unwrap();
2835
2836 assert_eq!(loaded_id, requested_id);
2837 assert_eq!(provider.count(), 1);
2838 assert_eq!(
2839 provider.get_instrument_id_by_contract_id(12_345),
2840 Some(requested_id)
2841 );
2842 assert_eq!(
2843 provider
2844 .resolve_instrument_id_for_contract(&details.contract)
2845 .unwrap(),
2846 requested_id
2847 );
2848
2849 let cached = provider.find(&requested_id).unwrap();
2850
2851 let InstrumentAny::OptionContract(option) = cached else {
2852 panic!("expected option contract");
2853 };
2854
2855 assert_eq!(option.id, requested_id);
2856 assert_eq!(option.id.venue.as_str(), "OPRA");
2857 assert!(
2858 provider
2859 .find(&InstrumentId::from("AAPL 270115P00155000.SMART"))
2860 .is_none()
2861 );
2862
2863 let cached_contract = provider
2864 .instrument_id_to_ib_contract(&requested_id)
2865 .unwrap();
2866 assert_eq!(cached_contract.contract_id, 12_345);
2867 assert_eq!(cached_contract.security_type, SecurityType::Option);
2868 assert_eq!(cached_contract.exchange.as_str(), "SMART");
2869
2870 let resolved_contract = provider
2871 .resolve_contract_for_instrument(requested_id)
2872 .unwrap();
2873 assert_eq!(resolved_contract, cached_contract);
2874
2875 let cached_details = provider
2876 .instrument_id_to_ib_contract_details(&requested_id)
2877 .unwrap();
2878 assert_eq!(cached_details.contract.contract_id, 12_345);
2879 assert_eq!(
2880 cached_details.valid_exchanges,
2881 vec!["SMART".to_string(), "CBOE".to_string()]
2882 );
2883 }
2884
2885 fn create_test_instrument_with_info(
2886 instrument_id: InstrumentId,
2887 info: Option<Params>,
2888 ) -> InstrumentAny {
2889 CurrencyPair::builder()
2890 .instrument_id(instrument_id)
2891 .raw_symbol(Symbol::from("EUR/USD"))
2892 .base_currency(Currency::from("EUR"))
2893 .quote_currency(Currency::from("USD"))
2894 .price_precision(4)
2895 .size_precision(0)
2896 .price_increment(Price::from("0.0001"))
2897 .size_increment(Quantity::from(1))
2898 .maybe_info(info)
2899 .ts_event(UnixNanos::default())
2900 .ts_init(UnixNanos::default())
2901 .build()
2902 .unwrap()
2903 .into()
2904 }
2905
2906 fn create_contract_info(contract: &Contract, price_magnifier: Option<i32>) -> Params {
2907 let mut info =
2908 IndexMap::from([(String::from("contract"), contract_to_json_value(contract))]);
2909
2910 if let Some(price_magnifier) = price_magnifier {
2911 info.insert(
2912 String::from("priceMagnifier"),
2913 serde_json::Value::from(price_magnifier),
2914 );
2915 }
2916
2917 Params::new(info)
2918 }
2919
2920 #[tokio::test]
2921 async fn test_initialize_loads_all_configured_inputs_once() {
2922 let instrument_id = InstrumentId::new(Symbol::from("AAPL"), Venue::from("NASDAQ"));
2923
2924 let contract_spec = Contract {
2925 security_type: SecurityType::Stock,
2926 symbol: ibapi::contracts::Symbol::from("MSFT"),
2927 exchange: Exchange::from("NASDAQ"),
2928 ..Default::default()
2929 };
2930
2931 let config = InteractiveBrokersInstrumentProviderConfig {
2932 load_ids: [instrument_id].into_iter().collect(),
2933 load_contracts: vec![ConfiguredContract::from(contract_spec)],
2934 ..Default::default()
2935 };
2936
2937 let provider = InteractiveBrokersInstrumentProvider::new(config).unwrap();
2938 let loader = TestStartupLoader::new(true, true);
2939
2940 let loaded_ids = provider.initialize_with_loader(&loader).await.unwrap();
2941 let second_result = provider.initialize_with_loader(&loader).await.unwrap();
2942
2943 assert_eq!(
2944 loaded_ids,
2945 vec![
2946 instrument_id,
2947 InstrumentId::new(Symbol::from("MSFT"), Venue::from("NASDAQ")),
2948 ]
2949 );
2950 assert!(second_result.is_empty());
2951 assert_eq!(loader.id_calls.load(Ordering::SeqCst), 1);
2952 assert_eq!(loader.contract_calls.load(Ordering::SeqCst), 1);
2953 assert!(*provider.startup_initialized.lock().await);
2954 }
2955
2956 #[tokio::test]
2957 async fn test_initialize_fails_closed_and_retries_unresolved_input() {
2958 let instrument_id = InstrumentId::new(Symbol::from("AAPL"), Venue::from("NASDAQ"));
2959
2960 let contract_spec = Contract {
2961 security_type: SecurityType::Stock,
2962 symbol: ibapi::contracts::Symbol::from("MSFT"),
2963 exchange: Exchange::from("NASDAQ"),
2964 ..Default::default()
2965 };
2966
2967 let config = InteractiveBrokersInstrumentProviderConfig {
2968 load_ids: [instrument_id].into_iter().collect(),
2969 load_contracts: vec![ConfiguredContract::from(contract_spec)],
2970 ..Default::default()
2971 };
2972
2973 let provider = InteractiveBrokersInstrumentProvider::new(config).unwrap();
2974 let loader = TestStartupLoader::new(true, false);
2975
2976 let error = provider.initialize_with_loader(&loader).await.unwrap_err();
2977
2978 assert!(error.to_string().contains("contract at index 0"));
2979 assert!(!*provider.startup_initialized.lock().await);
2980
2981 loader.resolve_contracts.store(true, Ordering::SeqCst);
2982 provider.initialize_with_loader(&loader).await.unwrap();
2983
2984 assert_eq!(loader.id_calls.load(Ordering::SeqCst), 2);
2985 assert_eq!(loader.contract_calls.load(Ordering::SeqCst), 2);
2986 assert!(*provider.startup_initialized.lock().await);
2987 }
2988
2989 #[tokio::test]
2990 async fn test_initialize_preserves_load_error_and_allows_retry() {
2991 let instrument_id = InstrumentId::new(Symbol::from("AAPL"), Venue::from("NASDAQ"));
2992
2993 let config = InteractiveBrokersInstrumentProviderConfig {
2994 load_ids: [instrument_id].into_iter().collect(),
2995 ..Default::default()
2996 };
2997
2998 let provider = InteractiveBrokersInstrumentProvider::new(config).unwrap();
2999 let loader = TestStartupLoader::new(true, true);
3000 loader.fail_next_id.store(true, Ordering::SeqCst);
3001
3002 let error = provider.initialize_with_loader(&loader).await.unwrap_err();
3003
3004 let error_chain = format!("{error:#}");
3005 assert!(error_chain.contains("Failed to load configured IB instrument ID AAPL.NASDAQ"));
3006 assert!(error_chain.contains("Socket disconnected"));
3007 assert!(!*provider.startup_initialized.lock().await);
3008
3009 provider.initialize_with_loader(&loader).await.unwrap();
3010
3011 assert_eq!(loader.id_calls.load(Ordering::SeqCst), 2);
3012 assert!(*provider.startup_initialized.lock().await);
3013 }
3014
3015 #[tokio::test]
3016 async fn test_initialize_serializes_concurrent_calls() {
3017 let instrument_id = InstrumentId::new(Symbol::from("AAPL"), Venue::from("NASDAQ"));
3018
3019 let config = InteractiveBrokersInstrumentProviderConfig {
3020 load_ids: [instrument_id].into_iter().collect(),
3021 ..Default::default()
3022 };
3023
3024 let provider = InteractiveBrokersInstrumentProvider::new(config).unwrap();
3025 let mut loader = TestStartupLoader::new(true, true);
3026 loader.yield_on_load = true;
3027
3028 let (first, second) = tokio::join!(
3029 provider.initialize_with_loader(&loader),
3030 provider.initialize_with_loader(&loader),
3031 );
3032
3033 assert_eq!(first.unwrap().len() + second.unwrap().len(), 1);
3034 assert_eq!(loader.id_calls.load(Ordering::SeqCst), 1);
3035 assert!(*provider.startup_initialized.lock().await);
3036 }
3037
3038 #[tokio::test]
3039 async fn test_save_cache() {
3040 let (provider, _temp_dir) = create_test_provider_with_cache();
3041 let cache_path = provider.config.cache_path.as_ref().unwrap().clone();
3042
3043 let instrument_id1 = InstrumentId::new(Symbol::from("EUR/USD"), Venue::from("IDEALPRO"));
3045 let instrument_id2 = InstrumentId::new(Symbol::from("GBP/USD"), Venue::from("IDEALPRO"));
3046
3047 let instrument1 = create_test_instrument(instrument_id1);
3048 let instrument2 = create_test_instrument(instrument_id2);
3049
3050 provider.instruments.insert(instrument_id1, instrument1);
3051 provider.instruments.insert(instrument_id2, instrument2);
3052 provider
3053 .contract_id_to_instrument_id
3054 .insert(100, instrument_id1);
3055 provider
3056 .contract_id_to_instrument_id
3057 .insert(200, instrument_id2);
3058 provider.price_magnifiers.insert(instrument_id1, 1);
3059 provider.price_magnifiers.insert(instrument_id2, 1);
3060
3061 let result = provider.save_cache(&cache_path).await;
3063 assert!(result.is_ok(), "save_cache should succeed");
3064
3065 assert!(Path::new(&cache_path).exists(), "Cache file should exist");
3067
3068 let contents = fs::read_to_string(&cache_path).unwrap();
3070 assert!(
3071 contents.contains("EUR/USD"),
3072 "Cache should contain instrument data"
3073 );
3074 assert!(
3075 contents.contains("cache_timestamp"),
3076 "Cache should contain timestamp"
3077 );
3078 }
3079
3080 #[tokio::test]
3081 async fn test_load_cache_valid() {
3082 let (provider, _temp_dir) = create_test_provider_with_cache();
3083 let cache_path = provider.config.cache_path.as_ref().unwrap().clone();
3084
3085 let instrument_id = InstrumentId::new(Symbol::from("EUR/USD"), Venue::from("IDEALPRO"));
3087 let instrument = create_test_instrument(instrument_id);
3088
3089 provider
3090 .instruments
3091 .insert(instrument_id, instrument.clone());
3092 provider
3093 .contract_id_to_instrument_id
3094 .insert(100, instrument_id);
3095 provider.price_magnifiers.insert(instrument_id, 1);
3096
3097 provider.save_cache(&cache_path).await.unwrap();
3098
3099 let new_config = InteractiveBrokersInstrumentProviderConfig::builder()
3101 .cache_path(cache_path.clone())
3102 .cache_validity_days(7u32)
3103 .build();
3104
3105 let new_provider = InteractiveBrokersInstrumentProvider::new(new_config).unwrap();
3106
3107 let result = new_provider.load_cache(&cache_path).await;
3108 assert!(result.is_ok(), "load_cache should succeed");
3109 assert!(
3110 result.unwrap(),
3111 "load_cache should return true for valid cache"
3112 );
3113
3114 assert!(
3116 new_provider.find(&instrument_id).is_some(),
3117 "Instrument should be loaded from cache"
3118 );
3119 assert_eq!(new_provider.count(), 1, "Provider should have 1 instrument");
3120 }
3121
3122 #[tokio::test]
3123 async fn test_load_cache_reads_chrono_timestamp() {
3124 let provider = InteractiveBrokersInstrumentProvider::new(
3125 InteractiveBrokersInstrumentProviderConfig::builder()
3126 .cache_validity_days(7u32)
3127 .build(),
3128 )
3129 .unwrap();
3130 let cache_path = concat!(
3131 env!("CARGO_MANIFEST_DIR"),
3132 "/test_data/instrument_cache_chrono.json"
3133 );
3134
3135 let loaded = provider.load_cache(cache_path).await.unwrap();
3136
3137 assert!(loaded);
3138 assert_eq!(provider.count(), 0);
3139 }
3140
3141 #[tokio::test]
3142 async fn test_load_cache_restores_contract_details() {
3143 let (provider, _temp_dir) = create_test_provider_with_cache();
3144 let cache_path = provider.config.cache_path.as_ref().unwrap().clone();
3145 let instrument_id = InstrumentId::new(Symbol::from("AAPL"), Venue::from("XNAS"));
3146 let instrument = create_test_instrument(instrument_id);
3147
3148 let contract = Contract {
3149 contract_id: 265598,
3150 symbol: ibapi::contracts::Symbol::from("AAPL"),
3151 security_type: SecurityType::Stock,
3152 exchange: Exchange::from("SMART"),
3153 primary_exchange: Exchange::from("NASDAQ"),
3154 currency: ibapi::contracts::Currency::from("USD"),
3155 ..Default::default()
3156 };
3157
3158 let details = ibapi::contracts::ContractDetails {
3159 contract: contract.clone(),
3160 price_magnifier: 1,
3161 ..Default::default()
3162 };
3163
3164 provider.cache_instrument(
3165 instrument_id,
3166 instrument,
3167 Some(details),
3168 Some(contract),
3169 Some(1),
3170 false,
3171 );
3172 provider.save_cache(&cache_path).await.unwrap();
3173
3174 let new_provider =
3175 InteractiveBrokersInstrumentProvider::new(provider.config.clone()).unwrap();
3176
3177 assert!(new_provider.load_cache(&cache_path).await.unwrap());
3178 assert_eq!(
3179 new_provider
3180 .resolve_contract_for_instrument(instrument_id)
3181 .unwrap()
3182 .contract_id,
3183 265598
3184 );
3185 assert_eq!(
3186 new_provider
3187 .instrument_id_to_ib_contract_details(&instrument_id)
3188 .unwrap()
3189 .contract
3190 .contract_id,
3191 265598
3192 );
3193 }
3194
3195 #[rstest]
3196 fn test_filter_sec_types_uses_typed_ib_codes() {
3197 let config = InteractiveBrokersInstrumentProviderConfig {
3198 filter_sec_types: [IbSecurityType::Option].into_iter().collect(),
3199 ..Default::default()
3200 };
3201
3202 let provider = InteractiveBrokersInstrumentProvider::new(config).unwrap();
3203
3204 assert!(provider.is_filtered_sec_type(&SecurityType::Option.to_string()));
3205 assert!(!provider.is_filtered_sec_type(&SecurityType::Stock.to_string()));
3206 }
3207
3208 #[rstest]
3209 fn test_add_cached_instruments_only_seeds_ib_contracts() {
3210 let provider = InteractiveBrokersInstrumentProvider::new(Default::default()).unwrap();
3211 let ib_instrument_id = InstrumentId::new(Symbol::from("AAPL"), Venue::from("XNAS"));
3212 let non_ib_instrument_id =
3213 InstrumentId::new(Symbol::from("BTCUSDT"), Venue::from("BINANCE"));
3214
3215 let contract = Contract {
3216 contract_id: 265598,
3217 symbol: ibapi::contracts::Symbol::from("AAPL"),
3218 security_type: SecurityType::Stock,
3219 exchange: Exchange::from("SMART"),
3220 primary_exchange: Exchange::from("NASDAQ"),
3221 currency: ibapi::contracts::Currency::from("USD"),
3222 ..Default::default()
3223 };
3224
3225 let ib_instrument = create_test_instrument_with_info(
3226 ib_instrument_id,
3227 Some(create_contract_info(&contract, Some(100))),
3228 );
3229 let non_ib_instrument = create_test_instrument(non_ib_instrument_id);
3230
3231 let count = provider.add_cached_instruments([ib_instrument, non_ib_instrument]);
3232
3233 assert_eq!(count, 1);
3234 assert_eq!(provider.count(), 1);
3235 assert!(provider.find(&ib_instrument_id).is_some());
3236 assert!(provider.find(&non_ib_instrument_id).is_none());
3237 assert_eq!(
3238 provider
3239 .resolve_contract_for_instrument(ib_instrument_id)
3240 .unwrap()
3241 .contract_id,
3242 265598
3243 );
3244 assert_eq!(provider.get_price_magnifier(&ib_instrument_id), 100);
3245 }
3246
3247 fn create_future_contract_with_expiry_time() -> Contract {
3248 Contract {
3249 contract_id: 515416632,
3250 symbol: ibapi::contracts::Symbol::from("ES"),
3251 security_type: SecurityType::Future,
3252 exchange: Exchange::from("CME"),
3253 currency: ibapi::contracts::Currency::from("USD"),
3254 local_symbol: String::from("ESZ6"),
3255 last_trade_date_or_contract_month: String::from("20261218 08:30:00 US/Central"),
3256 ..Default::default()
3257 }
3258 }
3259
3260 #[rstest]
3261 fn test_add_cached_instruments_cuts_stored_expiry_to_date() {
3262 let provider = InteractiveBrokersInstrumentProvider::new(Default::default()).unwrap();
3263 let instrument_id = InstrumentId::new(Symbol::from("ESZ6"), Venue::from("CME"));
3264 let contract = create_future_contract_with_expiry_time();
3265 let instrument = create_test_instrument_with_info(
3266 instrument_id,
3267 Some(create_contract_info(&contract, Some(1))),
3268 );
3269
3270 assert_eq!(provider.add_cached_instruments([instrument]), 1);
3271 assert_eq!(
3272 provider
3273 .resolve_contract_for_instrument(instrument_id)
3274 .unwrap()
3275 .last_trade_date_or_contract_month,
3276 "20261218"
3277 );
3278 }
3279
3280 #[rstest]
3281 #[case::instrument_info(false, false)]
3282 #[case::contract(true, false)]
3283 #[case::contract_details(true, true)]
3284 #[tokio::test]
3285 async fn test_load_cache_cuts_cached_expiry_to_date(
3286 #[case] with_contract: bool,
3287 #[case] with_details: bool,
3288 ) {
3289 let (provider, _temp_dir) = create_test_provider_with_cache();
3290 let cache_path = provider.config.cache_path.as_ref().unwrap().clone();
3291 let instrument_id = InstrumentId::new(Symbol::from("ESZ6"), Venue::from("CME"));
3292 let contract = create_future_contract_with_expiry_time();
3293 let instrument = create_test_instrument_with_info(
3294 instrument_id,
3295 Some(create_contract_info(&contract, Some(1))),
3296 );
3297 let details = ibapi::contracts::ContractDetails {
3298 contract: contract.clone(),
3299 price_magnifier: 1,
3300 time_zone_id: String::from("US/Central"),
3301 ..Default::default()
3302 };
3303
3304 provider.cache_instrument(
3305 instrument_id,
3306 instrument,
3307 with_details.then_some(details),
3308 with_contract.then_some(contract),
3309 Some(1),
3310 false,
3311 );
3312 provider.save_cache(&cache_path).await.unwrap();
3313
3314 let new_provider =
3315 InteractiveBrokersInstrumentProvider::new(provider.config.clone()).unwrap();
3316
3317 assert!(new_provider.load_cache(&cache_path).await.unwrap());
3318 assert_eq!(
3319 new_provider
3320 .resolve_contract_for_instrument(instrument_id)
3321 .unwrap()
3322 .last_trade_date_or_contract_month,
3323 "20261218"
3324 );
3325
3326 if with_details {
3327 let details = new_provider
3328 .instrument_id_to_ib_contract_details(&instrument_id)
3329 .unwrap();
3330 assert_eq!(
3331 details.contract.last_trade_date_or_contract_month,
3332 "20261218"
3333 );
3334 assert_eq!(details.last_trade_time, "08:30:00 US/Central");
3335 }
3336 }
3337
3338 #[tokio::test]
3339 async fn test_load_cache_missing_file() {
3340 let (provider, _temp_dir) = create_test_provider_with_cache();
3341 let cache_path = "/nonexistent/path/cache.json";
3342
3343 let result = provider.load_cache(cache_path).await;
3344 assert!(
3345 result.is_ok(),
3346 "load_cache should not error on missing file"
3347 );
3348 assert!(
3349 !result.unwrap(),
3350 "load_cache should return false for missing file"
3351 );
3352 }
3353
3354 #[tokio::test]
3355 async fn test_load_cache_expired() {
3356 let (provider, _temp_dir) = create_test_provider_with_cache();
3357 let cache_path = provider.config.cache_path.as_ref().unwrap().clone();
3358
3359 let old_timestamp = Timestamp::now() - jiff::SignedDuration::from_hours(24 * (10));
3361
3362 let expired_cache = InstrumentCache {
3363 cache_timestamp: old_timestamp,
3364 contract_id_to_instrument_id: vec![],
3365 price_magnifiers: vec![],
3366 contracts: vec![],
3367 contract_details: vec![],
3368 instruments: vec![],
3369 };
3370
3371 let json = serde_json::to_string_pretty(&expired_cache).unwrap();
3372 fs::write(&cache_path, json).unwrap();
3373
3374 let result = provider.load_cache(&cache_path).await;
3376 assert!(
3377 result.is_ok(),
3378 "load_cache should not error on expired cache"
3379 );
3380 assert!(
3381 !result.unwrap(),
3382 "load_cache should return false for expired cache"
3383 );
3384 }
3385 #[rstest]
3386 fn restored_cache_seeds_provider_with_price_magnifier() {
3387 let provider = InteractiveBrokersInstrumentProvider::new(Default::default()).unwrap();
3388 let mut cache = Cache::default();
3389 assert_eq!(provider.seed_from_cache(&cache), 0);
3390 let instrument_id = InstrumentId::from("AAPL.NASDAQ");
3391
3392 let contract = Contract {
3393 contract_id: 265598,
3394 symbol: ibapi::contracts::Symbol::from("AAPL"),
3395 security_type: SecurityType::Stock,
3396 exchange: Exchange::from("SMART"),
3397 currency: ibapi::contracts::Currency::from("USD"),
3398 ..Default::default()
3399 };
3400
3401 let instrument = create_test_instrument_with_info(
3402 instrument_id,
3403 Some(create_contract_info(&contract, Some(100))),
3404 );
3405 cache.add_instrument(instrument.clone()).unwrap();
3406 let seeded = provider.seed_from_cache(&cache);
3407 assert_eq!(seeded, 1);
3408 assert_eq!(provider.find(&instrument_id), Some(instrument));
3409 assert_eq!(provider.get_price_magnifier(&instrument_id), 100);
3410 assert_eq!(
3411 provider
3412 .resolve_contract_for_instrument(instrument_id)
3413 .unwrap(),
3414 contract
3415 );
3416 }
3417
3418 #[rstest]
3419 #[case(None)]
3420 #[case(Some(-1))]
3421 fn cached_instrument_without_valid_magnifier_requires_qualification(
3422 #[case] magnifier: Option<i32>,
3423 ) {
3424 let provider = InteractiveBrokersInstrumentProvider::new(Default::default()).unwrap();
3425 let instrument_id = InstrumentId::from("AAPL.NASDAQ");
3426
3427 let contract = Contract {
3428 contract_id: 265598,
3429 ..Default::default()
3430 };
3431
3432 let instrument = create_test_instrument_with_info(
3433 instrument_id,
3434 Some(create_contract_info(&contract, magnifier)),
3435 );
3436 assert_eq!(provider.add_cached_instruments([instrument]), 0);
3437 assert_eq!(provider.find(&instrument_id), None);
3438 }
3439
3440 #[rstest]
3441 fn price_magnifier_is_none_until_contract_metadata_is_loaded() {
3442 let provider = InteractiveBrokersInstrumentProvider::new(Default::default()).unwrap();
3443 let instrument_id = InstrumentId::from("ZCZ6.CBOT");
3444 provider
3445 .instruments
3446 .insert(instrument_id, create_test_instrument(instrument_id));
3447
3448 assert_eq!(provider.price_magnifier(&instrument_id), None);
3449 assert_eq!(provider.get_price_magnifier(&instrument_id), 1);
3450
3451 let details = ibapi::contracts::ContractDetails {
3452 price_magnifier: 100,
3453 ..Default::default()
3454 };
3455 provider.contract_details.insert(instrument_id, details);
3456
3457 assert_eq!(provider.price_magnifier(&instrument_id), Some(100));
3458 assert_eq!(provider.get_price_magnifier(&instrument_id), 100);
3459 }
3460
3461 #[rstest]
3462 fn instrument_cached_after_seeding_supplies_its_price_magnifier() {
3463 let provider = InteractiveBrokersInstrumentProvider::new(Default::default()).unwrap();
3464 let mut cache = Cache::default();
3465 let instrument_id = InstrumentId::from("ZCZ6.CBOT");
3466 assert_eq!(provider.seed_from_cache(&cache), 0);
3467 assert_eq!(
3468 provider.seed_price_magnifier_from_cache(&cache, &instrument_id),
3469 None
3470 );
3471
3472 let contract = Contract {
3473 contract_id: 815824252,
3474 symbol: ibapi::contracts::Symbol::from("ZC"),
3475 security_type: SecurityType::Future,
3476 exchange: Exchange::from("CBOT"),
3477 currency: ibapi::contracts::Currency::from("USD"),
3478 ..Default::default()
3479 };
3480 let instrument = create_test_instrument_with_info(
3481 instrument_id,
3482 Some(create_contract_info(&contract, Some(100))),
3483 );
3484 cache.add_instrument(instrument).unwrap();
3485
3486 assert_eq!(
3487 provider.seed_price_magnifier_from_cache(&cache, &instrument_id),
3488 Some(100)
3489 );
3490 assert_eq!(
3491 provider
3492 .resolve_contract_for_instrument(instrument_id)
3493 .unwrap(),
3494 contract
3495 );
3496 }
3497
3498 #[tokio::test]
3499 async fn ensure_price_magnifier_skips_the_request_when_the_magnifier_is_known() {
3500 let provider = InteractiveBrokersInstrumentProvider::new(Default::default()).unwrap();
3501 let instrument_id = InstrumentId::from("ZCZ6.CBOT");
3502 provider.price_magnifiers.insert(instrument_id, 100);
3503 let requests = AtomicUsize::new(0);
3504
3505 let magnifier = provider
3506 .ensure_price_magnifier_with(instrument_id, Duration::from_secs(5), || async {
3507 requests.fetch_add(1, Ordering::SeqCst);
3508 Ok(())
3509 })
3510 .await
3511 .unwrap();
3512
3513 assert_eq!(magnifier, 100);
3514 assert_eq!(requests.load(Ordering::SeqCst), 0);
3515 }
3516
3517 #[tokio::test]
3518 async fn ensure_price_magnifier_takes_it_from_requested_contract_details() {
3519 let provider = InteractiveBrokersInstrumentProvider::new(Default::default()).unwrap();
3520 let instrument_id = InstrumentId::from("ZCZ6.CBOT");
3521
3522 let magnifier = provider
3523 .ensure_price_magnifier_with(instrument_id, Duration::from_secs(5), || async {
3524 let details = ibapi::contracts::ContractDetails {
3525 price_magnifier: 100,
3526 ..Default::default()
3527 };
3528 provider.contract_details.insert(instrument_id, details);
3529 Ok(())
3530 })
3531 .await
3532 .unwrap();
3533
3534 assert_eq!(magnifier, 100);
3535 }
3536
3537 #[rstest]
3538 #[case::no_details(false, "IB price magnifier for ZCZ6.CBOT is unknown")]
3539 #[case::request_failed(true, "Failed to load IB contract details for ZCZ6.CBOT")]
3540 #[tokio::test]
3541 async fn ensure_price_magnifier_fails_when_ib_supplies_none(
3542 #[case] request_fails: bool,
3543 #[case] expected: &str,
3544 ) {
3545 let provider = InteractiveBrokersInstrumentProvider::new(Default::default()).unwrap();
3546 let instrument_id = InstrumentId::from("ZCZ6.CBOT");
3547
3548 let error = provider
3549 .ensure_price_magnifier_with(instrument_id, Duration::from_secs(5), || async {
3550 if request_fails {
3551 anyhow::bail!("Socket disconnected");
3552 }
3553 Ok(())
3554 })
3555 .await
3556 .unwrap_err();
3557
3558 assert!(format!("{error:#}").starts_with(expected), "{error:#}");
3559 assert_eq!(provider.price_magnifier(&instrument_id), None);
3560 }
3561
3562 #[rstest]
3563 #[tokio::test(start_paused = true)]
3564 async fn ensure_price_magnifier_times_out_when_the_request_never_completes() {
3565 let provider = InteractiveBrokersInstrumentProvider::new(Default::default()).unwrap();
3566 let instrument_id = InstrumentId::from("ZCZ6.CBOT");
3567 let timeout = Duration::from_secs(5);
3568 let start = tokio::time::Instant::now();
3569
3570 let error = provider
3571 .ensure_price_magnifier_with(instrument_id, timeout, std::future::pending)
3572 .await
3573 .unwrap_err();
3574
3575 assert_eq!(
3576 format!("{error:#}"),
3577 "Timed out after 5s loading IB contract details for ZCZ6.CBOT"
3578 );
3579 assert_eq!(tokio::time::Instant::now() - start, timeout);
3580 assert_eq!(provider.price_magnifier(&instrument_id), None);
3581 }
3582
3583 #[rstest]
3584 fn test_provider_rejects_duplicate_contracts_before_loading() {
3585 let config = serde_json::from_value(serde_json::json!({
3586 "load_contracts": [{"conId": 265598}, {"conId": 265598}]
3587 }))
3588 .unwrap();
3589 let error = InteractiveBrokersInstrumentProvider::new(config).unwrap_err();
3590
3591 assert_eq!(error, ConfigError::duplicate("load_contracts", None));
3592 }
3593}