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