Add read-only Client::config() (TWS 10.43 / server 219) (#707)

* Add read-only Client::config() (TWS 10.43 / server 219)

New config domain module exposing a one-shot Client::config() (sync +
async) that reads the TWS/Gateway configuration: API settings, order
precautions, smart-routing, lock-and-exit, and message prompts.

- ReqConfig -> ConfigResponse proto round-trip via one_shot_request_with_retry
- Idiomatic config::Config snapshot (no proto leak); every field optional
- Features::CONFIG gate (server_versions::CONFIG = 219)
- Register ConfigResponse in text_request_id_field so it routes by request_id
- Field-minimal testdata builders; 100% coverage on the new module

Read path only; update_config (write path with warning-ack) deferred.

* Add config examples (sync + async)

Smoke-tested against live IB Gateway paper (127.0.0.1:4002): the full
Config snapshot (lock-and-exit, message prompts, API settings,
precautions, smart-routing) decodes from real TWS wire data.

* Collapse redundant decode_config wrapper; narrow visibility

decode_config_message now calls require_proto()+decode inline; drop the
one-line decode_config indirection and the unused pub(crate) exposure
(decode_config_proto is module-private). No cross-module consumers.

* Reuse MessageBusStub::with_ordered_responses in config tests

Replace the hand-rolled stub struct literal with the existing named
constructor; drops the now-unused RwLock import.

Author: wboayue

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `Client::config()` (sync + async) to read the TWS/Gateway configuration (API settings, order precautions, smart-routing, lock-and-exit) added upstream for server version 219 (TWS 10.43); returns the new `config::Config` snapshot type and is gated behind `server_versions::CONFIG`.
 - `Order.hedge_max_size` (`Option<i32>`) for the maximum size of a hedge order, added upstream for server version 223 (TWS 10.45); gated behind `server_versions::HEDGE_MAX_SIZE` when placing orders (#706).
 - Server-version support advertised through 225 (`ODD_LOT_BID_ASK_QUOTES`), with new `server_versions` constants `FRACTIONAL_LAST_SIZE` (222), `HEDGE_MAX_SIZE` (223), `USE_PRECISION_FROM_SEC_DEF` (224), and `ODD_LOT_BID_ASK_QUOTES` (225) (#706).
 - `generic_tick::ODD_LOT` (`"787"`) request-side generic tick to subscribe odd-lot bid/ask quotes (server 225 / TWS 10.46) via `reqMktData` (#706).

Cargo.toml

@@ -110,6 +110,11 @@ name = "async_soft_dollar_tiers"
 path = "examples/async/soft_dollar_tiers.rs"
 required-features = ["async"]
 
+[[example]]
+name = "async_config"
+path = "examples/async/config.rs"
+required-features = ["async"]
+
 [[example]]
 name = "async_user_info"
 path = "examples/async/user_info.rs"
@@ -617,6 +622,11 @@ name = "soft_dollar_tiers"
 path = "examples/sync/soft_dollar_tiers.rs"
 required-features = ["sync"]
 
+[[example]]
+name = "config"
+path = "examples/sync/config.rs"
+required-features = ["sync"]
+
 [[example]]
 name = "user_info"
 path = "examples/sync/user_info.rs"

examples/async/config.rs

@@ -0,0 +1,21 @@
+//! Config example (async).
+//!
+//! Reads the TWS/Gateway configuration (API settings, order precautions,
+//! smart-routing, lock-and-exit) the gateway is currently running with.
+//!
+//! ```bash
+//! cargo run --example async_config
+//! ```
+
+use ibapi::prelude::*;
+
+#[tokio::main]
+async fn main() {
+    env_logger::init();
+
+    let client = Client::connect("127.0.0.1:4002", 100).await.expect("connection failed");
+
+    let config = client.config().await.expect("config request failed");
+
+    println!("{config:#?}");
+}

examples/sync/config.rs

@@ -0,0 +1,22 @@
+//! Config example (sync).
+//!
+//! Reads the TWS/Gateway configuration (API settings, order precautions,
+//! smart-routing, lock-and-exit) the gateway is currently running with.
+//!
+//! # Usage
+//!
+//! ```bash
+//! cargo run --features sync --example config
+//! ```
+
+use ibapi::client::blocking::Client;
+
+fn main() {
+    env_logger::init();
+
+    let client = Client::connect("127.0.0.1:4002", 100).expect("connection failed");
+
+    let config = client.config().expect("config request failed");
+
+    println!("{config:#?}");
+}

src/config/async.rs

@@ -0,0 +1,42 @@
+//! Asynchronous implementation of configuration retrieval.
+
+use crate::{
+    common::request_helpers,
+    protocol::{check_version, Features},
+    Client, Error,
+};
+
+use super::{common::decoders, encoders, Config};
+
+impl Client {
+    /// Reads the TWS/Gateway configuration (API, precautions, orders, and
+    /// lock-and-exit settings) the gateway is currently running with.
+    ///
+    /// This is a read-only snapshot; fields the gateway does not report are
+    /// left as `None`.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use ibapi::prelude::*;
+    ///
+    /// #[tokio::main]
+    /// async fn main() {
+    ///     let client = Client::connect("127.0.0.1:4002", 100).await.expect("connection failed");
+    ///     let config = client.config().await.expect("request config failed");
+    ///     println!("{config:?}");
+    /// }
+    /// ```
+    pub async fn config(&self) -> Result<Config, Error> {
+        check_version(self.server_version(), Features::CONFIG)?;
+
+        request_helpers::one_shot_request_with_retry(self, encoders::encode_request_config, decoders::decode_config_message, || {
+            Err(Error::UnexpectedEndOfStream)
+        })
+        .await
+    }
+}
+
+#[cfg(test)]
+#[path = "async_tests.rs"]
+mod tests;

src/config/async_tests.rs

@@ -0,0 +1,65 @@
+use super::*;
+use crate::common::test_utils::helpers::{assert_request, proto_response, TEST_REQ_ID_FIRST};
+use crate::messages::IncomingMessages;
+use crate::stubs::MessageBusStub;
+use crate::testdata::builders::config::{config_request, config_response};
+use crate::testdata::builders::ResponseProtoEncoder;
+use std::sync::Arc;
+
+fn stub(responses: Vec<crate::messages::ResponseMessage>) -> Arc<MessageBusStub> {
+    Arc::new(MessageBusStub::with_ordered_responses(responses))
+}
+
+#[tokio::test]
+async fn test_config_request_body() {
+    let message_bus = stub(vec![proto_response(
+        IncomingMessages::ConfigResponse,
+        config_response().request_id(TEST_REQ_ID_FIRST).encode_proto(),
+    )]);
+
+    let client = Client::stubbed(message_bus.clone(), crate::server_versions::CONFIG);
+    client.config().await.expect("config request failed");
+
+    assert_request(&message_bus, 0, &config_request().request_id(TEST_REQ_ID_FIRST));
+}
+
+#[tokio::test]
+async fn test_config_round_trip() {
+    let message_bus = stub(vec![proto_response(
+        IncomingMessages::ConfigResponse,
+        config_response()
+            .request_id(TEST_REQ_ID_FIRST)
+            .read_only_api(true)
+            .socket_port(4002)
+            .seek_price_improvement(true)
+            .encode_proto(),
+    )]);
+
+    let client = Client::stubbed(message_bus, crate::server_versions::CONFIG);
+    let config = client.config().await.expect("config request failed");
+
+    assert_eq!(config.api.unwrap().settings.unwrap().socket_port, Some(4002));
+    assert_eq!(config.orders.unwrap().smart_routing.unwrap().seek_price_improvement, Some(true));
+}
+
+#[tokio::test]
+async fn test_config_unexpected_end_of_stream() {
+    let message_bus = stub(vec![]);
+
+    let client = Client::stubbed(message_bus, crate::server_versions::CONFIG);
+    match client.config().await {
+        Err(Error::UnexpectedEndOfStream) => {}
+        other => panic!("expected UnexpectedEndOfStream, got {other:?}"),
+    }
+}
+
+#[tokio::test]
+async fn test_config_server_version_error() {
+    let message_bus = stub(vec![]);
+
+    let client = Client::stubbed(message_bus, crate::server_versions::CONFIG - 1);
+    match client.config().await {
+        Err(Error::ServerVersion(_, _, _)) => {}
+        other => panic!("expected ServerVersion error, got {other:?}"),
+    }
+}

src/config/common/decoders.rs

@@ -0,0 +1,130 @@
+//! Decoders for configuration messages. Proto-only; text framing surfaces as
+//! `Error::UnexpectedResponse` via `require_proto()`.
+
+use prost::Message;
+
+use crate::config::{ApiConfig, ApiPrecautions, ApiSettings, Config, LockAndExit, MessageSetting, OrdersConfig, OrdersSmartRouting};
+use crate::messages::{IncomingMessages, ResponseMessage};
+use crate::proto;
+use crate::Error;
+
+/// Dispatch on the incoming message type and forward to the typed decoder.
+/// Routes `Error` frames into `Error::from` and any other variant into
+/// `Error::UnexpectedResponse`.
+pub(in crate::config) fn decode_config_message(message: &ResponseMessage) -> Result<Config, Error> {
+    match message.message_type() {
+        IncomingMessages::ConfigResponse => decode_config_proto(message.require_proto()?),
+        IncomingMessages::Error => Err(Error::from(message)),
+        _ => Err(Error::unexpected_response(message)),
+    }
+}
+
+fn decode_config_proto(bytes: &[u8]) -> Result<Config, Error> {
+    let p = proto::ConfigResponse::decode(bytes)?;
+    Ok(Config {
+        lock_and_exit: p.lock_and_exit.map(convert_lock_and_exit),
+        messages: p.messages.into_iter().map(convert_message).collect(),
+        api: p.api.map(convert_api),
+        orders: p.orders.map(convert_orders),
+    })
+}
+
+fn convert_lock_and_exit(p: proto::LockAndExitConfig) -> LockAndExit {
+    LockAndExit {
+        auto_logoff_time: p.auto_logoff_time,
+        auto_logoff_period: p.auto_logoff_period,
+        auto_logoff_type: p.auto_logoff_type,
+    }
+}
+
+fn convert_message(p: proto::MessageConfig) -> MessageSetting {
+    MessageSetting {
+        id: p.id,
+        title: p.title,
+        message: p.message,
+        default_action: p.default_action,
+        enabled: p.enabled,
+    }
+}
+
+fn convert_api(p: proto::ApiConfig) -> ApiConfig {
+    ApiConfig {
+        precautions: p.precautions.map(convert_precautions),
+        settings: p.settings.map(convert_settings),
+    }
+}
+
+fn convert_precautions(p: proto::ApiPrecautionsConfig) -> ApiPrecautions {
+    ApiPrecautions {
+        bypass_order_precautions: p.bypass_order_precautions,
+        bypass_bond_warning: p.bypass_bond_warning,
+        bypass_negative_yield_confirmation: p.bypass_negative_yield_confirmation,
+        bypass_called_bond_warning: p.bypass_called_bond_warning,
+        bypass_same_action_pair_trade_warning: p.bypass_same_action_pair_trade_warning,
+        bypass_flagged_accounts_warning: p.bypass_flagged_accounts_warning,
+        bypass_price_based_volatility_warning: p.bypass_price_based_volatility_warning,
+        bypass_redirect_order_warning: p.bypass_redirect_order_warning,
+        bypass_no_overfill_protection: p.bypass_no_overfill_protection,
+        bypass_route_marketable_to_bbo: p.bypass_route_marketable_to_bbo,
+    }
+}
+
+fn convert_settings(p: proto::ApiSettingsConfig) -> ApiSettings {
+    ApiSettings {
+        read_only_api: p.read_only_api,
+        total_quantity_for_mutual_funds: p.total_quantity_for_mutual_funds,
+        download_open_orders_on_connection: p.download_open_orders_on_connection,
+        include_virtual_fx_positions: p.include_virtual_fx_positions,
+        prepare_daily_pnl: p.prepare_daily_pn_l,
+        send_status_updates_for_volatility_orders: p.send_status_updates_for_volatility_orders,
+        encode_api_messages: p.encode_api_messages,
+        socket_port: p.socket_port,
+        use_negative_auto_range: p.use_negative_auto_range,
+        create_api_message_log_file: p.create_api_message_log_file,
+        include_market_data_in_log_file: p.include_market_data_in_log_file,
+        expose_trading_schedule_to_api: p.expose_trading_schedule_to_api,
+        split_insured_deposit_from_cash_balance: p.split_insured_deposit_from_cash_balance,
+        send_zero_positions_for_today_only: p.send_zero_positions_for_today_only,
+        let_api_account_requests_switch_subscription: p.let_api_account_requests_switch_subscription,
+        use_account_groups_with_allocation_methods: p.use_account_groups_with_allocation_methods,
+        logging_level: p.logging_level,
+        master_client_id: p.master_client_id,
+        bulk_data_timeout: p.bulk_data_timeout,
+        component_exch_separator: p.component_exch_separator,
+        show_forex_data_in_1_10_pips: p.show_forex_data_in1_10pips,
+        allow_forex_trading_in_1_10_pips: p.allow_forex_trading_in1_10pips,
+        round_account_values_to_nearest_whole_number: p.round_account_values_to_nearest_whole_number,
+        send_market_data_in_lots_for_us_stocks: p.send_market_data_in_lots_for_us_stocks,
+        show_advanced_order_reject_in_ui: p.show_advanced_order_reject_in_ui,
+        reject_messages_above_max_rate: p.reject_messages_above_max_rate,
+        maintain_connection_on_incorrect_fields: p.maintain_connection_on_incorrect_fields,
+        compatibility_mode_nasdaq_stocks: p.compatibility_mode_nasdaq_stocks,
+        send_instrument_timezone: p.send_instrument_timezone,
+        send_forex_data_in_compatibility_mode: p.send_forex_data_in_compatibility_mode,
+        maintain_and_resubmit_orders_on_reconnect: p.maintain_and_resubmit_orders_on_reconnect,
+        historical_data_max_size: p.historical_data_max_size,
+        auto_report_netting_event_contract_trades: p.auto_report_netting_event_contract_trades,
+        option_exercise_request_type: p.option_exercise_request_type,
+        allow_localhost_only: p.allow_localhost_only,
+        trusted_ips: p.trusted_i_ps,
+    }
+}
+
+fn convert_orders(p: proto::OrdersConfig) -> OrdersConfig {
+    OrdersConfig {
+        smart_routing: p.smart_routing.map(convert_smart_routing),
+    }
+}
+
+fn convert_smart_routing(p: proto::OrdersSmartRoutingConfig) -> OrdersSmartRouting {
+    OrdersSmartRouting {
+        seek_price_improvement: p.seek_price_improvement,
+        pre_open_reroute: p.pre_open_reroute,
+        do_not_route_to_dark_pools: p.do_not_route_to_dark_pools,
+        default_algorithm: p.default_algorithm,
+    }
+}
+
+#[cfg(test)]
+#[path = "decoders_tests.rs"]
+mod tests;