rust-ibapi

Routing for request_id-keyed subscriptions relies on a deliberate allow-list called text_request_id_field (located in src/messages.rs).

Core Concepts:

• The Allow-list: text_request_id_field is not a sentinel; it is an explicit allow-list. This prevents misrouting messages where an integer at tag 1 might represent something other than a request ID (e.g., MarketRule.market_rule_id).
• Routing Logic: routes_by_request_id() is a thin wrapper over this table. The table must contain the correct text-frame field index (e.g., 1 vs 2).
• Validation: The function debug_assert_request_id_routable in src/subscriptions/common.rs validates this during subscription construction. It will panic if a request_id-keyed subscription is built for a decoder whose RESPONSE_MESSAGE_IDS includes a type that the dispatcher cannot route (i.e., a type missing from the text_request_id_field table).

Condition builders (like PriceCondition) use the type-state pattern to ensure valid configuration. This prevents invalid states (like setting a threshold without a direction) at compile time:

1. Constructor: Initialize with required fields (e.g., PriceCondition::builder(contract_id, exchange)).
2. Threshold & Direction: Set these atomically using methods like .greater_than(value) or .less_than(value). This prevents the error of setting a threshold but forgetting the direction.
3. Optional Config: Chain methods like .trigger_method(TriggerMethod::Last) or .conjunction(true).
4. Conversion: Finalize the builder using .build() or rely on automatic Into<OrderCondition> conversion.

use ibapi::orders::conditions::{PriceCondition, TriggerMethod};

let condition = PriceCondition::builder(265598, "SMART")
    .greater_than(150.0)
    .trigger_method(TriggerMethod::Last)
    .build();

The project uses a partitioned ID space to prevent collisions between Request IDs and Order IDs. A specific floor value, REQUEST_ID_FLOOR (set to $2^{30}$ or 1_073_741_824), is used to separate these domains.

Key Concepts:

• Partitioning: Request IDs and Order IDs are separated by a floor. Request IDs typically reside in the lower range, while Order IDs are moved to the range above the floor.
• Typed IDs: The library uses specific types RequestId and OrderId instead of raw i32 to prevent logic errors (like using a request ID where an order ID is expected).
• Validation: Order entry points validate that IDs do not cross into the request ID partition. If an ID is invalid (e.g., an Order ID is provided that is below the floor or is a reserved value), the API will return an InvalidArgument error.

ID Behavior:

• next_request_id() returns values at or above 1_073_741_824.
• Order IDs provided to place_order, submit_order, or cancel_order are checked against the floor. If they violate the partition, they are rejected with Error::InvalidArgument before being sent to the wire.

When you make an API call (e.g., req_contract_details), the following sequence occurs:

1. Client: Generates a Request ID and encodes the request.
2. MessageBus: Receives the request, creates a dedicated response channel, and forwards the message to the Connection manager.
3. Connection: Sends the request via a TCP socket to TWS/Gateway.
4. TWS/Gateway: Processes the request and sends a response.
5. Connection: Receives the response and parses it.
6. MessageBus: Routes the parsed response back to the Client using the Request ID.
7. Client: Decodes the response and returns the result to your application.

Message Routing Patterns

• Requests with IDs: The MessageBus uses dedicated channels for these responses.
• Requests without IDs: The MessageBus uses shared channels.
• Order-based requests: These receive special handling for tracking purposes.

When creating a new API module, follow a consistent directory structure to support both synchronous and asynchronous modes. The module should be organized as follows:

• src/<module>/mod.rs: Contains public types and module exports. This file should define types that are available regardless of feature flags.
• src/<module>/common/: Contains shared implementation details used by both sync and async implementations.
  • mod.rs: Exports encoders/decoders.
  • encoders.rs: Message encoding functions.
  • decoders.rs: Protobuf decoding functions.
  • test_tables.rs: (Optional) Shared test cases.
• src/<module>/sync.rs: Synchronous implementation.
• src/<module>/async.rs: Asynchronous implementation.
• src/<module>/sync_tests.rs: Tests for the synchronous implementation (use a flat sibling file, do not use inline mod tests).
• src/<module>/async_tests.rs: Tests for the asynchronous implementation.

Note: Response fixtures should not live in the module. They belong in src/testdata/builders/<domain>.rs, with one builder per domain implementing ResponseProtoEncoder.

// src/<module>/mod.rs
//! Module description

// Common implementation modules
mod common;

// Feature-specific implementations
#[cfg(feature = "sync")]
mod sync;

#[cfg(feature = "async")]
mod r#async;

// Public types - always available regardless of feature flags
#[derive(Debug)]
pub struct MyData {
    pub field: String,
}