Skip to main content

nautilus_interactive_brokers/providers/
instruments.rs

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