rustrade_execution/client/ibkr/

contract.rs

//! Contract builders for IB integration.

use crate::error::ConnectivityError;
use ibapi::contracts::{Contract, Currency, Exchange, OptionRight, SecurityType, Symbol};
use thiserror::Error;

/// Reasons a [`ContractConfig`](super::ContractConfig) cannot be mapped to a
/// valid [`Contract`].
///
/// Every variant represents an input that would otherwise force the builder to
/// silently fabricate a *wrong* contract (e.g. defaulting a missing option
/// `right` to Call, or an unknown `security_type` to a stock). Surfacing these
/// at construction — rather than deferring to an opaque IBKR submission
/// rejection — keeps failures observable, per the library's contract.
///
/// `#[non_exhaustive]`: new validation reasons may be added without a breaking
/// change as the contract builders grow.
#[derive(Debug, Clone, PartialEq, Eq, Error)]
#[non_exhaustive]
pub enum ContractConfigError {
    /// An `OPT` contract was configured without a `right`.
    #[error("OPT contract requires a `right` field (expected one of C/CALL/P/PUT)")]
    MissingOptionRight,

    /// A `right` was supplied but is not one of `C`/`CALL`/`P`/`PUT`.
    #[error("unrecognized option right {right:?} (expected one of C/CALL/P/PUT)")]
    UnrecognizedOptionRight { right: String },

    /// An `OPT` contract was configured without a `strike`.
    #[error("OPT contract requires a `strike` field")]
    MissingStrike,

    /// A `FUT` or `OPT` contract was configured without a `last_trade_date`.
    #[error("FUT/OPT contract requires a `last_trade_date` field")]
    MissingLastTradeDate,

    /// The `security_type` is not one of the supported `STK`/`FUT`/`OPT`/`CASH`.
    #[error("unrecognized security_type {security_type:?} (expected one of STK/FUT/OPT/CASH)")]
    UnrecognizedSecurityType { security_type: String },
}

/// Reasons [`IbkrClient::resolve_contract`](super::IbkrClient::resolve_contract) cannot
/// resolve a contract description into one IB contract.
///
/// `#[non_exhaustive]`: new reasons may be added without a breaking change.
#[derive(Debug, Clone, PartialEq, Error)]
#[non_exhaustive]
pub enum ResolveContractError {
    /// No IB contract matches the description.
    #[error("no IB contract matches the description")]
    NoMatch,

    /// Several IB contracts match the description, for example the same symbol on several
    /// exchanges, or options of several trading classes. Narrow the description, or pick one of
    /// `matches` and register it.
    #[error(
        "{} IB contracts match the description (contract ids {:?}); narrow it",
        .matches.len(),
        contract_ids(.matches)
    )]
    Ambiguous {
        /// Every contract that matches, as IB resolved it.
        matches: Vec<Contract>,
    },

    /// IB answered the request with an error other than finding no match, such as a description
    /// it cannot validate. Retrying the same description usually fails the same way, so
    /// [`is_transient`](Self::is_transient) is false. Some IB errors, such as a pacing
    /// violation, can clear on a later retry: tell those apart by `code`.
    #[error("IB refused the contract details request (error {code}): {message}")]
    Refused {
        /// IB's error code.
        code: i32,
        /// IB's error message.
        message: String,
    },

    /// The connection dropped, or IB sent nothing for 10 s before finishing its answer.
    /// Transient: retry once `ibapi` has reconnected.
    #[error("contract details request failed: {0}")]
    Connectivity(#[from] ConnectivityError),

    /// The request could not be made or read for another reason: the client shut down or gave
    /// up reconnecting, `ibapi` could not decode IB's answer, or the blocking task failed.
    /// Retrying on this client does not help.
    #[error("contract details request failed: {0}")]
    Failed(String),
}

impl ResolveContractError {
    /// Whether the same request may succeed if retried: a
    /// [`Connectivity`](Self::Connectivity) failure.
    pub fn is_transient(&self) -> bool {
        matches!(self, Self::Connectivity(e) if e.is_transient())
    }
}

fn contract_ids(contracts: &[Contract]) -> Vec<i32> {
    contracts
        .iter()
        .map(|contract| contract.contract_id)
        .collect()
}

/// Map a human/wire option-right string to `OptionRight`.
///
/// Accepts IBKR wire values (`"C"`/`"P"`) and common long forms
/// (`"CALL"`/`"PUT"`), case-insensitively. Returns `None` for anything else.
fn parse_option_right(right: &str) -> Option<OptionRight> {
    let right = right.trim();
    if right.eq_ignore_ascii_case("C") || right.eq_ignore_ascii_case("CALL") {
        Some(OptionRight::Call)
    } else if right.eq_ignore_ascii_case("P") || right.eq_ignore_ascii_case("PUT") {
        Some(OptionRight::Put)
    } else {
        None
    }
}

/// Build a stock contract for the given symbol.
pub fn stock_contract(symbol: &str, exchange: &str, currency: &str) -> Contract {
    Contract::stock(symbol)
        .on_exchange(exchange)
        .in_currency(currency)
        .build()
}

/// Build a futures contract.
pub fn futures_contract(
    symbol: &str,
    last_trade_date: &str,
    exchange: &str,
    currency: &str,
) -> Contract {
    Contract {
        symbol: Symbol::new(symbol),
        security_type: SecurityType::Future,
        last_trade_date_or_contract_month: last_trade_date.to_string(),
        exchange: Exchange::new(exchange),
        currency: Currency::new(currency),
        ..Default::default()
    }
}

/// Build an options contract.
///
/// # Errors
///
/// Returns [`ContractConfigError::UnrecognizedOptionRight`] if `right` is not
/// one of `C`/`CALL`/`P`/`PUT` (case-insensitive; leading and trailing
/// whitespace is ignored). An option contract is invalid without a valid right,
/// so this is surfaced at construction rather than as a later IBKR submission
/// rejection.
///
/// Only `right` is validated here. `last_trade_date` and `strike` are forwarded
/// to the IBKR contract as-is; an empty date or a `0.0` strike will build a
/// (quietly wrong) contract. Presence of those fields is checked one level up in
/// [`ContractConfig`](super::ContractConfig)'s `to_contract`, which is
/// the intended entry point for config-driven construction.
pub fn option_contract(
    symbol: &str,
    last_trade_date: &str,
    strike: f64,
    right: &str,
    exchange: &str,
    currency: &str,
) -> Result<Contract, ContractConfigError> {
    let right =
        parse_option_right(right).ok_or_else(|| ContractConfigError::UnrecognizedOptionRight {
            right: right.to_string(),
        })?;
    Ok(Contract {
        symbol: Symbol::new(symbol),
        security_type: SecurityType::Option,
        last_trade_date_or_contract_month: last_trade_date.to_string(),
        strike,
        right: Some(right),
        exchange: Exchange::new(exchange),
        currency: Currency::new(currency),
        ..Default::default()
    })
}

/// Build a forex contract.
pub fn forex_contract(symbol: &str, currency: &str) -> Contract {
    Contract {
        symbol: Symbol::new(symbol),
        security_type: SecurityType::ForexPair,
        exchange: Exchange::new("IDEALPRO"),
        currency: Currency::new(currency),
        ..Default::default()
    }
}