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