ibapi 5.1.0

//! Message encoding, decoding, and routing for TWS API communication.
//!
//! This module handles the low-level message protocol between the client and TWS,
//! including request/response message formatting, field encoding/decoding,
//! and message type definitions.

use std::fmt::Display;
use std::io::Write;
use std::str::{self, FromStr};

use byteorder::{BigEndian, WriteBytesExt};

use serde::{Deserialize, Serialize};
use time::OffsetDateTime;

use crate::{Error, ToField};

pub(crate) mod shared_channel_configuration;
#[cfg(test)]
mod tests;

/// Offset added to outbound protobuf message IDs. Inbound IDs > this value are protobuf.
pub(crate) const PROTOBUF_MSG_ID: i32 = 200;

/// Width of the big-endian message id that opens every frame body:
/// `[4-byte BE msg_id][payload]`.
pub(crate) const MESSAGE_ID_LEN: usize = 4;

/// Messages emitted by TWS/Gateway over the market data socket.
#[derive(Debug, Default, PartialEq, Eq, Hash, Copy, Clone)]
pub enum IncomingMessages {
    /// Gateway initiated shutdown.
    Shutdown = -2,
    /// Unknown or unsupported message id.
    #[default]
    NotValid = -1,
    /// Tick price update.
    TickPrice = 1,
    /// Tick size update.
    TickSize = 2,
    /// Order status update.
    OrderStatus = 3,
    /// Error (includes request id and code).
    Error = 4,
    /// Open order description.
    OpenOrder = 5,
    /// Account value key/value pair.
    AccountValue = 6,
    /// Portfolio value line.
    PortfolioValue = 7,
    /// Account update timestamp.
    AccountUpdateTime = 8,
    /// Next valid order id notification.
    NextValidId = 9,
    /// Contract details payload.
    ContractData = 10,
    /// Execution data update.
    ExecutionData = 11,
    /// Level 1 market depth row update.
    MarketDepth = 12,
    /// Level 2 market depth row update.
    MarketDepthL2 = 13,
    /// News bulletin broadcast.
    NewsBulletins = 14,
    /// List of managed accounts.
    ManagedAccounts = 15,
    /// Financial advisor configuration data.
    ReceiveFA = 16,
    /// Historical bar data payload.
    HistoricalData = 17,
    /// Bond contract details payload.
    BondContractData = 18,
    /// Scanner parameter definitions.
    ScannerParameters = 19,
    /// Scanner subscription results.
    ScannerData = 20,
    /// Option computation tick.
    TickOptionComputation = 21,
    /// Generic numeric tick (e.g. implied volatility).
    TickGeneric = 45,
    /// String-valued tick (exchange names, etc.).
    TickString = 46,
    /// Exchange for Physical tick update.
    TickEFP = 47, //TICK EFP 47
    /// Current world clock time.
    CurrentTime = 49,
    /// Real-time bars update.
    RealTimeBars = 50,
    /// Fundamental data response. IBKR removed the fundamental-data feature in
    /// TWS 10.47; no decoder claims this id, but the variant is retained so
    /// `From<i32>` maps id 51 to a known-but-unclaimed message type (see `TickEFP`).
    FundamentalData = 51,
    /// End marker for contract details batches.
    ContractDataEnd = 52,
    /// End marker for open order batches.
    OpenOrderEnd = 53,
    /// End marker for account download.
    AccountDownloadEnd = 54,
    /// End marker for execution data.
    ExecutionDataEnd = 55,
    /// Delta-neutral validation response.
    DeltaNeutralValidation = 56,
    /// End of tick snapshot.
    TickSnapshotEnd = 57,
    /// Market data type acknowledgment.
    MarketDataType = 58,
    /// Commissions report payload.
    CommissionsReport = 59,
    /// Position update.
    Position = 61,
    /// End marker for position updates.
    PositionEnd = 62,
    /// Account summary update.
    AccountSummary = 63,
    /// End marker for account summary stream.
    AccountSummaryEnd = 64,
    /// API verification challenge.
    VerifyMessageApi = 65,
    /// API verification completion.
    VerifyCompleted = 66,
    /// Display group list response.
    DisplayGroupList = 67,
    /// Display group update.
    DisplayGroupUpdated = 68,
    /// Auth + verification challenge.
    VerifyAndAuthMessageApi = 69,
    /// Auth + verification completion.
    VerifyAndAuthCompleted = 70,
    /// Multi-account position update.
    PositionMulti = 71,
    /// End marker for multi-account position stream.
    PositionMultiEnd = 72,
    /// Multi-account account update.
    AccountUpdateMulti = 73,
    /// End marker for multi-account account stream.
    AccountUpdateMultiEnd = 74,
    /// Option security definition parameters.
    SecurityDefinitionOptionParameter = 75,
    /// End marker for option security definition stream.
    SecurityDefinitionOptionParameterEnd = 76,
    /// Soft dollar tier information.
    SoftDollarTier = 77,
    /// Family code response.
    FamilyCodes = 78,
    /// Matching symbol samples.
    SymbolSamples = 79,
    /// Exchanges offering market depth.
    MktDepthExchanges = 80,
    /// Tick request parameter info.
    TickReqParams = 81,
    /// Smart component routing map.
    SmartComponents = 82,
    /// News article content.
    NewsArticle = 83,
    /// News headline tick.
    TickNews = 84,
    /// Available news providers.
    NewsProviders = 85,
    /// Historical news headlines.
    HistoricalNews = 86,
    /// End marker for historical news.
    HistoricalNewsEnd = 87,
    /// Head timestamp for historical data.
    HeadTimestamp = 88,
    /// Histogram data response.
    HistogramData = 89,
    /// Streaming historical data update.
    HistoricalDataUpdate = 90,
    /// Market data request reroute notice.
    RerouteMktDataReq = 91,
    /// Market depth request reroute notice.
    RerouteMktDepthReq = 92,
    /// Market rule response.
    MarketRule = 93,
    /// Account PnL update.
    PnL = 94,
    /// Single position PnL update.
    PnLSingle = 95,
    /// Historical tick data (midpoint).
    HistoricalTick = 96,
    /// Historical tick data (bid/ask).
    HistoricalTickBidAsk = 97,
    /// Historical tick data (trades).
    HistoricalTickLast = 98,
    /// Tick-by-tick streaming data.
    TickByTick = 99,
    /// Order bound notification for API multiple endpoints.
    OrderBound = 100,
    /// Completed order information.
    CompletedOrder = 101,
    /// End marker for completed orders.
    CompletedOrdersEnd = 102,
    /// End marker for FA profile replacement.
    ReplaceFAEnd = 103,
    /// Wall Street Horizon metadata update.
    WshMetaData = 104,
    /// Wall Street Horizon event payload.
    WshEventData = 105,
    /// Historical schedule response.
    HistoricalSchedule = 106,
    /// User information response.
    UserInfo = 107,
    /// End marker for historical data.
    HistoricalDataEnd = 108,
    /// Current time in milliseconds.
    CurrentTimeInMillis = 109,
    /// Configuration response.
    ConfigResponse = 110,
    /// Update configuration response.
    UpdateConfigResponse = 111,
}

impl From<i32> for IncomingMessages {
    fn from(value: i32) -> IncomingMessages {
        match value {
            -2 => IncomingMessages::Shutdown,
            1 => IncomingMessages::TickPrice,
            2 => IncomingMessages::TickSize,
            3 => IncomingMessages::OrderStatus,
            4 => IncomingMessages::Error,
            5 => IncomingMessages::OpenOrder,
            6 => IncomingMessages::AccountValue,
            7 => IncomingMessages::PortfolioValue,
            8 => IncomingMessages::AccountUpdateTime,
            9 => IncomingMessages::NextValidId,
            10 => IncomingMessages::ContractData,
            11 => IncomingMessages::ExecutionData,
            12 => IncomingMessages::MarketDepth,
            13 => IncomingMessages::MarketDepthL2,
            14 => IncomingMessages::NewsBulletins,
            15 => IncomingMessages::ManagedAccounts,
            16 => IncomingMessages::ReceiveFA,
            17 => IncomingMessages::HistoricalData,
            18 => IncomingMessages::BondContractData,
            19 => IncomingMessages::ScannerParameters,
            20 => IncomingMessages::ScannerData,
            21 => IncomingMessages::TickOptionComputation,
            45 => IncomingMessages::TickGeneric,
            46 => IncomingMessages::TickString,
            47 => IncomingMessages::TickEFP, //TICK EFP 47
            49 => IncomingMessages::CurrentTime,
            50 => IncomingMessages::RealTimeBars,
            51 => IncomingMessages::FundamentalData,
            52 => IncomingMessages::ContractDataEnd,
            53 => IncomingMessages::OpenOrderEnd,
            54 => IncomingMessages::AccountDownloadEnd,
            55 => IncomingMessages::ExecutionDataEnd,
            56 => IncomingMessages::DeltaNeutralValidation,
            57 => IncomingMessages::TickSnapshotEnd,
            58 => IncomingMessages::MarketDataType,
            59 => IncomingMessages::CommissionsReport,
            61 => IncomingMessages::Position,
            62 => IncomingMessages::PositionEnd,
            63 => IncomingMessages::AccountSummary,
            64 => IncomingMessages::AccountSummaryEnd,
            65 => IncomingMessages::VerifyMessageApi,
            66 => IncomingMessages::VerifyCompleted,
            67 => IncomingMessages::DisplayGroupList,
            68 => IncomingMessages::DisplayGroupUpdated,
            69 => IncomingMessages::VerifyAndAuthMessageApi,
            70 => IncomingMessages::VerifyAndAuthCompleted,
            71 => IncomingMessages::PositionMulti,
            72 => IncomingMessages::PositionMultiEnd,
            73 => IncomingMessages::AccountUpdateMulti,
            74 => IncomingMessages::AccountUpdateMultiEnd,
            75 => IncomingMessages::SecurityDefinitionOptionParameter,
            76 => IncomingMessages::SecurityDefinitionOptionParameterEnd,
            77 => IncomingMessages::SoftDollarTier,
            78 => IncomingMessages::FamilyCodes,
            79 => IncomingMessages::SymbolSamples,
            80 => IncomingMessages::MktDepthExchanges,
            81 => IncomingMessages::TickReqParams,
            82 => IncomingMessages::SmartComponents,
            83 => IncomingMessages::NewsArticle,
            84 => IncomingMessages::TickNews,
            85 => IncomingMessages::NewsProviders,
            86 => IncomingMessages::HistoricalNews,
            87 => IncomingMessages::HistoricalNewsEnd,
            88 => IncomingMessages::HeadTimestamp,
            89 => IncomingMessages::HistogramData,
            90 => IncomingMessages::HistoricalDataUpdate,
            91 => IncomingMessages::RerouteMktDataReq,
            92 => IncomingMessages::RerouteMktDepthReq,
            93 => IncomingMessages::MarketRule,
            94 => IncomingMessages::PnL,
            95 => IncomingMessages::PnLSingle,
            96 => IncomingMessages::HistoricalTick,
            97 => IncomingMessages::HistoricalTickBidAsk,
            98 => IncomingMessages::HistoricalTickLast,
            99 => IncomingMessages::TickByTick,
            100 => IncomingMessages::OrderBound,
            101 => IncomingMessages::CompletedOrder,
            102 => IncomingMessages::CompletedOrdersEnd,
            103 => IncomingMessages::ReplaceFAEnd,
            104 => IncomingMessages::WshMetaData,
            105 => IncomingMessages::WshEventData,
            106 => IncomingMessages::HistoricalSchedule,
            107 => IncomingMessages::UserInfo,
            108 => IncomingMessages::HistoricalDataEnd,
            109 => IncomingMessages::CurrentTimeInMillis,
            110 => IncomingMessages::ConfigResponse,
            111 => IncomingMessages::UpdateConfigResponse,
            _ => IncomingMessages::NotValid,
        }
    }
}

impl FromStr for IncomingMessages {
    type Err = Error;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.parse::<i32>() {
            Ok(n) => Ok(IncomingMessages::from(n)),
            Err(_) => Err(Error::parse_field(s, "invalid incoming message type")),
        }
    }
}

/// Allow-list of incoming message types that route by `request_id`.
///
/// `ResponseMessage::request_id()` decodes the proto envelope only when the
/// message type appears here; this prevents misrouting messages that happen
/// to carry an unrelated `int32 @ tag 1` (e.g. `MarketRule.market_rule_id`,
/// `OrderBound.perm_id`). Derived from [`text_request_id_field`] — every
/// known request-scoped message has a text-frame fallback index, so a single
/// table is the source of truth.
pub(crate) fn routes_by_request_id(kind: IncomingMessages) -> bool {
    text_request_id_field(kind).is_some()
}

/// Text-format field index carrying the request id, for messages parsed
/// from pipe-delimited text framing. Doubles as the routing allow-list (see
/// [`routes_by_request_id`]).
///
/// At floor 213 no production message arrives text-framed — proto-framed
/// messages decode the request id via the envelope in `raw_bytes` instead.
/// The table remains because tests still construct text-framed
/// [`ResponseMessage`] fixtures for many proto-only message types.
/// `ExecutionData{,End}` are present because the order router falls back to
/// the request_id channel after a missed order_id lookup. `OpenOrder` routes
/// as an order message before request-id routing is considered, so its entry
/// here never routes it.
pub(crate) fn text_request_id_field(kind: IncomingMessages) -> Option<usize> {
    match kind {
        IncomingMessages::AccountSummary
        | IncomingMessages::AccountSummaryEnd
        | IncomingMessages::AccountUpdateMulti
        | IncomingMessages::AccountUpdateMultiEnd
        | IncomingMessages::ContractDataEnd
        | IncomingMessages::DisplayGroupList
        | IncomingMessages::DisplayGroupUpdated
        | IncomingMessages::ExecutionDataEnd
        | IncomingMessages::MarketDataType
        | IncomingMessages::MarketDepth
        | IncomingMessages::MarketDepthL2
        | IncomingMessages::PositionMulti
        | IncomingMessages::PositionMultiEnd
        | IncomingMessages::RealTimeBars
        | IncomingMessages::ScannerData
        | IncomingMessages::TickGeneric
        | IncomingMessages::TickPrice
        | IncomingMessages::TickSize
        | IncomingMessages::TickSnapshotEnd
        | IncomingMessages::TickString => Some(2),

        IncomingMessages::ConfigResponse
        | IncomingMessages::UpdateConfigResponse
        | IncomingMessages::BondContractData
        | IncomingMessages::ContractData
        | IncomingMessages::ExecutionData
        | IncomingMessages::HeadTimestamp
        | IncomingMessages::HistogramData
        | IncomingMessages::HistoricalData
        | IncomingMessages::HistoricalDataEnd
        | IncomingMessages::HistoricalDataUpdate
        | IncomingMessages::HistoricalNews
        | IncomingMessages::HistoricalNewsEnd
        | IncomingMessages::HistoricalSchedule
        | IncomingMessages::HistoricalTick
        | IncomingMessages::HistoricalTickBidAsk
        | IncomingMessages::HistoricalTickLast
        | IncomingMessages::NewsArticle
        | IncomingMessages::OpenOrder
        | IncomingMessages::PnL
        | IncomingMessages::PnLSingle
        | IncomingMessages::ReplaceFAEnd
        | IncomingMessages::SecurityDefinitionOptionParameter
        | IncomingMessages::SecurityDefinitionOptionParameterEnd
        | IncomingMessages::SmartComponents
        | IncomingMessages::SoftDollarTier
        | IncomingMessages::SymbolSamples
        | IncomingMessages::TickByTick
        | IncomingMessages::TickNews
        | IncomingMessages::TickOptionComputation
        | IncomingMessages::TickReqParams
        | IncomingMessages::UserInfo
        | IncomingMessages::WshEventData
        | IncomingMessages::WshMetaData => Some(1),

        _ => None,
    }
}

/// Outgoing message opcodes understood by TWS/Gateway.
#[allow(dead_code)]
#[derive(Debug, Copy, Clone, Eq, Hash, PartialEq)]
pub enum OutgoingMessages {
    /// Request streaming market data.
    RequestMarketData = 1,
    /// Cancel streaming market data.
    CancelMarketData = 2,
    /// Submit a new order.
    PlaceOrder = 3,
    /// Cancel an existing order.
    CancelOrder = 4,
    /// Request the current open orders.
    RequestOpenOrders = 5,
    /// Request account value updates.
    RequestAccountData = 6,
    /// Request execution reports.
    RequestExecutions = 7,
    /// Request a block of valid order ids.
    RequestIds = 8,
    /// Request contract details.
    RequestContractData = 9,
    /// Request level-two market depth.
    RequestMarketDepth = 10,
    /// Cancel level-two market depth.
    CancelMarketDepth = 11,
    /// Subscribe to news bulletins.
    RequestNewsBulletins = 12,
    /// Cancel news bulletin subscription.
    CancelNewsBulletin = 13,
    /// Change the server log level.
    ChangeServerLog = 14,
    /// Request auto-open orders.
    RequestAutoOpenOrders = 15,
    /// Request all open orders.
    RequestAllOpenOrders = 16,
    /// Request managed accounts list.
    RequestManagedAccounts = 17,
    /// Request financial advisor configuration.
    RequestFA = 18,
    /// Replace financial advisor configuration.
    ReplaceFA = 19,
    /// Request historical bar data.
    RequestHistoricalData = 20,
    /// Exercise an option contract.
    ExerciseOptions = 21,
    /// Subscribe to a market scanner.
    RequestScannerSubscription = 22,
    /// Cancel a market scanner subscription.
    CancelScannerSubscription = 23,
    /// Request scanner parameter definitions.
    RequestScannerParameters = 24,
    /// Cancel an in-flight historical data request.
    CancelHistoricalData = 25,
    /// Request the current TWS/Gateway time.
    RequestCurrentTime = 49,
    /// Request real-time bars.
    RequestRealTimeBars = 50,
    /// Cancel real-time bars.
    CancelRealTimeBars = 51,
    /// Request fundamental data.
    RequestFundamentalData = 52,
    /// Cancel fundamental data.
    CancelFundamentalData = 53,
    /// Request implied volatility calculation.
    ReqCalcImpliedVolat = 54,
    /// Request option price calculation.
    ReqCalcOptionPrice = 55,
    /// Cancel implied volatility calculation.
    CancelImpliedVolatility = 56,
    /// Cancel option price calculation.
    CancelOptionPrice = 57,
    /// Issue a global cancel request.
    RequestGlobalCancel = 58,
    /// Change the active market data type.
    RequestMarketDataType = 59,
    /// Subscribe to position updates.
    RequestPositions = 61,
    /// Subscribe to account summary.
    RequestAccountSummary = 62,
    /// Cancel account summary subscription.
    CancelAccountSummary = 63,
    /// Cancel position subscription.
    CancelPositions = 64,
    /// Begin API verification handshake.
    VerifyRequest = 65,
    /// Respond to verification handshake.
    VerifyMessage = 66,
    /// Query display groups.
    QueryDisplayGroups = 67,
    /// Subscribe to display group events.
    SubscribeToGroupEvents = 68,
    /// Update a display group subscription.
    UpdateDisplayGroup = 69,
    /// Unsubscribe from display group events.
    UnsubscribeFromGroupEvents = 70,
    /// Start the API session.
    StartApi = 71,
    /// Verification handshake with auth.
    VerifyAndAuthRequest = 72,
    /// Verification message with auth.
    VerifyAndAuthMessage = 73,
    /// Request multi-account/model positions.
    RequestPositionsMulti = 74,
    /// Cancel multi-account/model positions.
    CancelPositionsMulti = 75,
    /// Request multi-account/model updates.
    RequestAccountUpdatesMulti = 76,
    /// Cancel multi-account/model updates.
    CancelAccountUpdatesMulti = 77,
    /// Request option security definition parameters.
    RequestSecurityDefinitionOptionalParameters = 78,
    /// Request soft-dollar tier definitions.
    RequestSoftDollarTiers = 79,
    /// Request family codes.
    RequestFamilyCodes = 80,
    /// Request matching symbols.
    RequestMatchingSymbols = 81,
    /// Request exchanges that support depth.
    RequestMktDepthExchanges = 82,
    /// Request smart routing component map.
    RequestSmartComponents = 83,
    /// Request detailed news article.
    RequestNewsArticle = 84,
    /// Request available news providers.
    RequestNewsProviders = 85,
    /// Request historical news headlines.
    RequestHistoricalNews = 86,
    /// Request earliest timestamp for historical data.
    RequestHeadTimestamp = 87,
    /// Request histogram snapshot.
    RequestHistogramData = 88,
    /// Cancel histogram snapshot.
    CancelHistogramData = 89,
    /// Cancel head timestamp request.
    CancelHeadTimestamp = 90,
    /// Request market rule definition.
    RequestMarketRule = 91,
    /// Request account-wide PnL stream.
    RequestPnL = 92,
    /// Cancel account-wide PnL stream.
    CancelPnL = 93,
    /// Request single-position PnL stream.
    RequestPnLSingle = 94,
    /// Cancel single-position PnL stream.
    CancelPnLSingle = 95,
    /// Request historical tick data.
    RequestHistoricalTicks = 96,
    /// Request tick-by-tick data.
    RequestTickByTickData = 97,
    /// Cancel tick-by-tick data.
    CancelTickByTickData = 98,
    /// Request completed order history.
    RequestCompletedOrders = 99,
    /// Request Wall Street Horizon metadata.
    RequestWshMetaData = 100,
    /// Cancel Wall Street Horizon metadata.
    CancelWshMetaData = 101,
    /// Request Wall Street Horizon event data.
    RequestWshEventData = 102,
    /// Cancel Wall Street Horizon event data.
    CancelWshEventData = 103,
    /// Request user information.
    RequestUserInfo = 104,
    /// Request current time in milliseconds.
    RequestCurrentTimeInMillis = 105,
    /// Cancel contract data request.
    CancelContractData = 106,
    /// Cancel historical ticks request.
    CancelHistoricalTicks = 107,
    /// Request configuration.
    ReqConfig = 108,
    /// Update configuration.
    UpdateConfig = 109,
}

impl ToField for OutgoingMessages {
    fn to_field(&self) -> String {
        (*self as i32).to_string()
    }
}

impl std::fmt::Display for OutgoingMessages {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", *self as i32)
    }
}

impl TryFrom<i32> for OutgoingMessages {
    type Error = Error;

    fn try_from(id: i32) -> Result<Self, Self::Error> {
        match id {
            1 => Ok(OutgoingMessages::RequestMarketData),
            2 => Ok(OutgoingMessages::CancelMarketData),
            3 => Ok(OutgoingMessages::PlaceOrder),
            4 => Ok(OutgoingMessages::CancelOrder),
            5 => Ok(OutgoingMessages::RequestOpenOrders),
            6 => Ok(OutgoingMessages::RequestAccountData),
            7 => Ok(OutgoingMessages::RequestExecutions),
            8 => Ok(OutgoingMessages::RequestIds),
            9 => Ok(OutgoingMessages::RequestContractData),
            10 => Ok(OutgoingMessages::RequestMarketDepth),
            11 => Ok(OutgoingMessages::CancelMarketDepth),
            12 => Ok(OutgoingMessages::RequestNewsBulletins),
            13 => Ok(OutgoingMessages::CancelNewsBulletin),
            14 => Ok(OutgoingMessages::ChangeServerLog),
            15 => Ok(OutgoingMessages::RequestAutoOpenOrders),
            16 => Ok(OutgoingMessages::RequestAllOpenOrders),
            17 => Ok(OutgoingMessages::RequestManagedAccounts),
            18 => Ok(OutgoingMessages::RequestFA),
            19 => Ok(OutgoingMessages::ReplaceFA),
            20 => Ok(OutgoingMessages::RequestHistoricalData),
            21 => Ok(OutgoingMessages::ExerciseOptions),
            22 => Ok(OutgoingMessages::RequestScannerSubscription),
            23 => Ok(OutgoingMessages::CancelScannerSubscription),
            24 => Ok(OutgoingMessages::RequestScannerParameters),
            25 => Ok(OutgoingMessages::CancelHistoricalData),
            49 => Ok(OutgoingMessages::RequestCurrentTime),
            50 => Ok(OutgoingMessages::RequestRealTimeBars),
            51 => Ok(OutgoingMessages::CancelRealTimeBars),
            52 => Ok(OutgoingMessages::RequestFundamentalData),
            53 => Ok(OutgoingMessages::CancelFundamentalData),
            54 => Ok(OutgoingMessages::ReqCalcImpliedVolat),
            55 => Ok(OutgoingMessages::ReqCalcOptionPrice),
            56 => Ok(OutgoingMessages::CancelImpliedVolatility),
            57 => Ok(OutgoingMessages::CancelOptionPrice),
            58 => Ok(OutgoingMessages::RequestGlobalCancel),
            59 => Ok(OutgoingMessages::RequestMarketDataType),
            61 => Ok(OutgoingMessages::RequestPositions),
            62 => Ok(OutgoingMessages::RequestAccountSummary),
            63 => Ok(OutgoingMessages::CancelAccountSummary),
            64 => Ok(OutgoingMessages::CancelPositions),
            65 => Ok(OutgoingMessages::VerifyRequest),
            66 => Ok(OutgoingMessages::VerifyMessage),
            67 => Ok(OutgoingMessages::QueryDisplayGroups),
            68 => Ok(OutgoingMessages::SubscribeToGroupEvents),
            69 => Ok(OutgoingMessages::UpdateDisplayGroup),
            70 => Ok(OutgoingMessages::UnsubscribeFromGroupEvents),
            71 => Ok(OutgoingMessages::StartApi),
            72 => Ok(OutgoingMessages::VerifyAndAuthRequest),
            73 => Ok(OutgoingMessages::VerifyAndAuthMessage),
            74 => Ok(OutgoingMessages::RequestPositionsMulti),
            75 => Ok(OutgoingMessages::CancelPositionsMulti),
            76 => Ok(OutgoingMessages::RequestAccountUpdatesMulti),
            77 => Ok(OutgoingMessages::CancelAccountUpdatesMulti),
            78 => Ok(OutgoingMessages::RequestSecurityDefinitionOptionalParameters),
            79 => Ok(OutgoingMessages::RequestSoftDollarTiers),
            80 => Ok(OutgoingMessages::RequestFamilyCodes),
            81 => Ok(OutgoingMessages::RequestMatchingSymbols),
            82 => Ok(OutgoingMessages::RequestMktDepthExchanges),
            83 => Ok(OutgoingMessages::RequestSmartComponents),
            84 => Ok(OutgoingMessages::RequestNewsArticle),
            85 => Ok(OutgoingMessages::RequestNewsProviders),
            86 => Ok(OutgoingMessages::RequestHistoricalNews),
            87 => Ok(OutgoingMessages::RequestHeadTimestamp),
            88 => Ok(OutgoingMessages::RequestHistogramData),
            89 => Ok(OutgoingMessages::CancelHistogramData),
            90 => Ok(OutgoingMessages::CancelHeadTimestamp),
            91 => Ok(OutgoingMessages::RequestMarketRule),
            92 => Ok(OutgoingMessages::RequestPnL),
            93 => Ok(OutgoingMessages::CancelPnL),
            94 => Ok(OutgoingMessages::RequestPnLSingle),
            95 => Ok(OutgoingMessages::CancelPnLSingle),
            96 => Ok(OutgoingMessages::RequestHistoricalTicks),
            97 => Ok(OutgoingMessages::RequestTickByTickData),
            98 => Ok(OutgoingMessages::CancelTickByTickData),
            99 => Ok(OutgoingMessages::RequestCompletedOrders),
            100 => Ok(OutgoingMessages::RequestWshMetaData),
            101 => Ok(OutgoingMessages::CancelWshMetaData),
            102 => Ok(OutgoingMessages::RequestWshEventData),
            103 => Ok(OutgoingMessages::CancelWshEventData),
            104 => Ok(OutgoingMessages::RequestUserInfo),
            105 => Ok(OutgoingMessages::RequestCurrentTimeInMillis),
            106 => Ok(OutgoingMessages::CancelContractData),
            107 => Ok(OutgoingMessages::CancelHistoricalTicks),
            108 => Ok(OutgoingMessages::ReqConfig),
            109 => Ok(OutgoingMessages::UpdateConfig),
            n => Err(Error::parse_field(n.to_string(), "unknown outgoing message type")),
        }
    }
}

impl FromStr for OutgoingMessages {
    type Err = Error;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let id = s.parse::<i32>().map_err(|_| Error::parse_field(s, "invalid outgoing message type"))?;
        OutgoingMessages::try_from(id)
    }
}

impl OutgoingMessages {
    /// Whether this message stops something already running: a `Cancel*`,
    /// the global order cancel, or leaving display-group events. The outbound
    /// rate limiter sends these without waiting. Exhaustive so a new variant
    /// forces a decision.
    ///
    /// Cancels that reuse a request id with a flag, such as
    /// `RequestAccountData` with `subscribe = false`, are not recognized and
    /// wait like requests: slower, never over the limit.
    pub(crate) fn is_cancel(self) -> bool {
        match self {
            OutgoingMessages::CancelMarketData
            | OutgoingMessages::CancelOrder
            | OutgoingMessages::CancelMarketDepth
            | OutgoingMessages::CancelNewsBulletin
            | OutgoingMessages::CancelScannerSubscription
            | OutgoingMessages::CancelHistoricalData
            | OutgoingMessages::CancelRealTimeBars
            | OutgoingMessages::CancelFundamentalData
            | OutgoingMessages::CancelImpliedVolatility
            | OutgoingMessages::CancelOptionPrice
            | OutgoingMessages::CancelAccountSummary
            | OutgoingMessages::CancelPositions
            | OutgoingMessages::CancelPositionsMulti
            | OutgoingMessages::CancelAccountUpdatesMulti
            | OutgoingMessages::CancelHistogramData
            | OutgoingMessages::CancelHeadTimestamp
            | OutgoingMessages::CancelPnL
            | OutgoingMessages::CancelPnLSingle
            | OutgoingMessages::CancelTickByTickData
            | OutgoingMessages::CancelWshMetaData
            | OutgoingMessages::CancelWshEventData
            | OutgoingMessages::CancelContractData
            | OutgoingMessages::CancelHistoricalTicks
            | OutgoingMessages::RequestGlobalCancel
            | OutgoingMessages::UnsubscribeFromGroupEvents => true,
            OutgoingMessages::RequestMarketData
            | OutgoingMessages::PlaceOrder
            | OutgoingMessages::RequestOpenOrders
            | OutgoingMessages::RequestAccountData
            | OutgoingMessages::RequestExecutions
            | OutgoingMessages::RequestIds
            | OutgoingMessages::RequestContractData
            | OutgoingMessages::RequestMarketDepth
            | OutgoingMessages::RequestNewsBulletins
            | OutgoingMessages::ChangeServerLog
            | OutgoingMessages::RequestAutoOpenOrders
            | OutgoingMessages::RequestAllOpenOrders
            | OutgoingMessages::RequestManagedAccounts
            | OutgoingMessages::RequestFA
            | OutgoingMessages::ReplaceFA
            | OutgoingMessages::RequestHistoricalData
            | OutgoingMessages::ExerciseOptions
            | OutgoingMessages::RequestScannerSubscription
            | OutgoingMessages::RequestScannerParameters
            | OutgoingMessages::RequestCurrentTime
            | OutgoingMessages::RequestRealTimeBars
            | OutgoingMessages::RequestFundamentalData
            | OutgoingMessages::ReqCalcImpliedVolat
            | OutgoingMessages::ReqCalcOptionPrice
            | OutgoingMessages::RequestMarketDataType
            | OutgoingMessages::RequestPositions
            | OutgoingMessages::RequestAccountSummary
            | OutgoingMessages::VerifyRequest
            | OutgoingMessages::VerifyMessage
            | OutgoingMessages::QueryDisplayGroups
            | OutgoingMessages::SubscribeToGroupEvents
            | OutgoingMessages::UpdateDisplayGroup
            | OutgoingMessages::StartApi
            | OutgoingMessages::VerifyAndAuthRequest
            | OutgoingMessages::VerifyAndAuthMessage
            | OutgoingMessages::RequestPositionsMulti
            | OutgoingMessages::RequestAccountUpdatesMulti
            | OutgoingMessages::RequestSecurityDefinitionOptionalParameters
            | OutgoingMessages::RequestSoftDollarTiers
            | OutgoingMessages::RequestFamilyCodes
            | OutgoingMessages::RequestMatchingSymbols
            | OutgoingMessages::RequestMktDepthExchanges
            | OutgoingMessages::RequestSmartComponents
            | OutgoingMessages::RequestNewsArticle
            | OutgoingMessages::RequestNewsProviders
            | OutgoingMessages::RequestHistoricalNews
            | OutgoingMessages::RequestHeadTimestamp
            | OutgoingMessages::RequestHistogramData
            | OutgoingMessages::RequestMarketRule
            | OutgoingMessages::RequestPnL
            | OutgoingMessages::RequestPnLSingle
            | OutgoingMessages::RequestHistoricalTicks
            | OutgoingMessages::RequestTickByTickData
            | OutgoingMessages::RequestCompletedOrders
            | OutgoingMessages::RequestWshMetaData
            | OutgoingMessages::RequestWshEventData
            | OutgoingMessages::RequestUserInfo
            | OutgoingMessages::RequestCurrentTimeInMillis
            | OutgoingMessages::ReqConfig
            | OutgoingMessages::UpdateConfig => false,
        }
    }
}

/// Encode the outbound message length prefix using the IB wire format.
pub(crate) fn encode_length(message: &str) -> Vec<u8> {
    encode_raw_length(message.as_bytes())
}

/// Encode a protobuf outbound message: 4-byte BE (msg_id + 200) + proto bytes.
pub(crate) fn encode_protobuf_message(msg_id: i32, proto_bytes: &[u8]) -> Vec<u8> {
    let mut buf = Vec::with_capacity(MESSAGE_ID_LEN + proto_bytes.len());
    buf.write_i32::<BigEndian>(msg_id + PROTOBUF_MSG_ID).unwrap();
    buf.extend_from_slice(proto_bytes);
    buf
}

/// Split a frame body into its 4-byte BE message id, as sent (protobuf ids
/// still carry the [`PROTOBUF_MSG_ID`] offset), and the payload. `None` if the
/// body is too short to hold an id.
pub(crate) fn split_message_id(frame: &[u8]) -> Option<(i32, &[u8])> {
    let (header, payload) = frame.split_first_chunk::<MESSAGE_ID_LEN>()?;
    Some((i32::from_be_bytes(*header), payload))
}

/// The request kind of an outbound frame body, or `None` if the id is missing
/// or unknown.
pub(crate) fn outgoing_message_type(frame: &[u8]) -> Option<OutgoingMessages> {
    let (id, _) = split_message_id(frame)?;
    let id = if id > PROTOBUF_MSG_ID { id - PROTOBUF_MSG_ID } else { id };
    OutgoingMessages::try_from(id).ok()
}

/// Whether an outbound frame body is a cancel (see [`OutgoingMessages::is_cancel`]).
pub(crate) fn is_cancel_frame(frame: &[u8]) -> bool {
    outgoing_message_type(frame).is_some_and(OutgoingMessages::is_cancel)
}

/// Encode a length-prefixed raw message (4-byte BE length + data).
pub(crate) fn encode_raw_length(data: &[u8]) -> Vec<u8> {
    let mut packet = Vec::with_capacity(data.len() + 4);
    packet.write_u32::<BigEndian>(data.len() as u32).unwrap();
    packet.write_all(data).unwrap();
    packet
}

/// Builder for outbound TWS/Gateway request messages (test-only).
#[cfg(test)]
#[derive(Default, Debug, Clone)]
pub(crate) struct RequestMessage {
    pub(crate) fields: Vec<String>,
}

#[cfg(all(test, feature = "sync"))]
impl RequestMessage {
    /// Serialize all fields into the NUL-delimited wire format.
    pub(crate) fn encode(&self) -> String {
        let mut data = self.fields.join("\0");
        data.push('\0');
        data
    }

    /// Serialize the message as a pipe-delimited string (test helper).
    pub(crate) fn encode_simple(&self) -> String {
        let mut data = self.fields.join("|");
        data.push('|');
        data
    }

    /// Construct a request message from a NUL-delimited string (test helper).
    pub(crate) fn from(fields: &str) -> RequestMessage {
        RequestMessage {
            fields: fields.split_terminator('\x00').map(|x| x.to_string()).collect(),
        }
    }

    /// Construct a request message from a pipe-delimited string (test helper).
    pub(crate) fn from_simple(fields: &str) -> RequestMessage {
        RequestMessage {
            fields: fields.split_terminator('|').map(|x| x.to_string()).collect(),
        }
    }
}

#[cfg(test)]
impl std::ops::Index<usize> for RequestMessage {
    type Output = String;

    fn index(&self, i: usize) -> &Self::Output {
        &self.fields[i]
    }
}

/// Minimal protobuf envelope decoding the int32 at tag 1. Covers `request_id`
/// across most TWS protobuf messages and `order_id` for `OpenOrder` /
/// `OrderStatus` / `ExecutionDetailsEnd`. Avoids the full struct decode
/// (`OpenOrder` nests `Contract` + `Order` + `OrderState` — ~30 String
/// allocations) just to read one int32; prost length-prefix-skips unknown
/// trailing tags.
#[derive(Clone, Copy, PartialEq, Eq, ::prost::Message)]
struct ProtoIdEnvelope {
    #[prost(int32, optional, tag = "1")]
    pub id: Option<i32>,
}

/// Minimal envelope for `ExecutionDetails` reading only the nested
/// `execution.order_id` (tag 3 → tag 1) and `execution.exec_id` (tag 3 →
/// tag 2). Skips the `contract` sub-message at tag 2, avoiding ~20 String
/// allocations per inbound `ExecutionData`.
#[derive(Clone, PartialEq, ::prost::Message)]
struct ExecutionDetailsMinimal {
    #[prost(message, optional, tag = "3")]
    pub execution: Option<ExecutionMinimal>,
}

#[derive(Clone, PartialEq, ::prost::Message)]
struct ExecutionMinimal {
    #[prost(int32, optional, tag = "1")]
    pub order_id: Option<i32>,
    #[prost(string, optional, tag = "2")]
    pub exec_id: Option<String>,
}

/// Parsed inbound message from TWS/Gateway.
///
/// Crate-internal wire envelope; not part of the public API. All fields,
/// constructors, and methods are crate-visible only. Framing is discriminated
/// by `raw_bytes`: `Some(_)` = protobuf payload, `None` = NUL-delimited text
/// payload pre-parsed into `fields` (carries WSH metadata/event-data, plus
/// unhandled text-framed message types that fall through to the dispatcher
/// catch-all).
#[derive(Clone, Default, Debug)]
pub(crate) struct ResponseMessage {
    /// Cursor index for incremental decoding.
    pub i: usize,
    /// Raw field buffer backing this message. Empty for protobuf frames, whose
    /// payload lives in `raw_bytes` and whose discriminant lives in `kind`.
    pub fields: Vec<String>,
    /// Raw protobuf payload bytes (everything after the 4-byte binary message ID).
    pub raw_bytes: Option<Vec<u8>>,
    /// The message discriminant, resolved once at construction.
    ///
    /// Read 4–6 times per inbound message — routing, request-id extraction, the
    /// subscription's `RESPONSE_MESSAGE_IDS` filter, the decoder's own match —
    /// each of which used to re-run `i32::from_str` over `fields[0]`.
    kind: IncomingMessages,
    /// The numeric id `kind` was resolved from, retained because that mapping
    /// is lossy: every unrecognized id collapses to
    /// [`IncomingMessages::NotValid`]. See [`UNKNOWN_MESSAGE_TYPE_CODE`] for
    /// what the id buys a reader that the kind alone cannot. `None` when the
    /// message carried no id at all (a text payload with a missing or
    /// unparsable `fields[0]`, or `Default`); no `i32` can stand in for that,
    /// since 0 and negative ids both reach the text path off the wire.
    message_id: Option<i32>,
}

impl ResponseMessage {
    /// The one construction path, so `kind` and `message_id` cannot disagree:
    /// `kind` is `IncomingMessages::from(id)`, or `NotValid` with no id. The
    /// derived `Default` upholds it too: `None` and `NotValid`, the enum's
    /// `#[default]`.
    fn new(message_id: Option<i32>, fields: Vec<String>, raw_bytes: Option<Vec<u8>>) -> Self {
        Self {
            i: 0,
            fields,
            raw_bytes,
            kind: message_id.map_or(IncomingMessages::NotValid, IncomingMessages::from),
            message_id,
        }
    }

    /// Build a protobuf response message from a binary message type and raw payload bytes.
    pub fn from_protobuf(message_type: i32, raw_bytes: Vec<u8>) -> Self {
        Self::new(Some(message_type), Vec::new(), Some(raw_bytes))
    }

    /// The numeric message id this frame arrived with, before it was resolved
    /// to an [`IncomingMessages`] kind. For protobuf frames this is the id with
    /// the [`PROTOBUF_MSG_ID`] offset already removed — i.e. the value that was
    /// looked up, not the raw 4 bytes off the wire.
    ///
    /// Always `Some` for protobuf frames; `None` only for a text payload
    /// whose `fields[0]` is missing or unparsable.
    ///
    /// Guaranteed for every message, not just unroutable ones:
    /// `m.message_id().map_or(NotValid, IncomingMessages::from) == m.message_type()`.
    /// Callers that need the id back out of a message — the wire recorder,
    /// diagnostics for an unrecognized frame — depend on that holding for known
    /// kinds too.
    pub(crate) fn message_id(&self) -> Option<i32> {
        self.message_id
    }

    /// Raw protobuf payload bytes, if this is a protobuf message.
    pub fn raw_bytes(&self) -> Option<&[u8]> {
        self.raw_bytes.as_deref()
    }

    /// Raw protobuf payload bytes for use by proto-only decoders. Text-framed
    /// arrival returns `Error::UnexpectedWireFormat`, which fails the
    /// subscription — the message was addressed to this decoder, so dropping it
    /// would lose data. Nothing here is skipped: whether a message belongs to a
    /// subscription is decided from `RESPONSE_MESSAGE_IDS` before decoding. See
    /// docs/rules/wire/proto-only-decoding.md.
    pub(crate) fn require_proto(&self) -> Result<&[u8], crate::Error> {
        self.raw_bytes().ok_or_else(|| crate::Error::unexpected_wire_format(self))
    }

    /// Narrow a frame to one expected message type, or fail with
    /// `Error::UnexpectedResponse`.
    ///
    /// [`Self::require_proto`]'s sibling on the other axis: that one narrows the
    /// framing, this one narrows the type. Both return a borrow so they chain in
    /// the position the decoder wants.
    ///
    /// One-shot request paths should not call this directly — they compose both
    /// narrows through `request_helpers::expect_proto`, which takes the expected
    /// type alongside the payload decoder so a call site cannot supply one
    /// without the other.
    ///
    /// There is deliberately no `IncomingMessages::Error` case. The dispatcher
    /// classifies error frames before any decoder sees them, so one cannot
    /// arrive here — see `docs/rules/wire/proto-only-decoding.md`.
    pub(crate) fn expect_type(&self, expected: IncomingMessages) -> Result<&Self, Error> {
        if self.message_type() == expected {
            Ok(self)
        } else {
            Err(Error::UnexpectedResponse(format!("expected {expected:?}, got {self:?}")))
        }
    }

    /// Returns `true` if the message informs about API shutdown.
    #[cfg_attr(not(feature = "sync"), allow(dead_code))] // sync-transport-only caller
    pub fn is_shutdown(&self) -> bool {
        self.message_type() == IncomingMessages::Shutdown
    }

    /// Return the discriminator identifying the message payload.
    pub fn message_type(&self) -> IncomingMessages {
        self.kind
    }

    /// Try to extract the request id from the message.
    ///
    /// Proto-framed messages carry it at proto tag 1 in `raw_bytes`. The
    /// text-framed branch reads the per-message-type field index — at floor
    /// 213 no production message arrives text-framed, so this path is
    /// unreachable through production decoders but exercised by tests.
    /// Returns `None` for any message type not in the [`routes_by_request_id`]
    /// allow-list, even if its proto envelope happens to carry an `int32 @
    /// tag 1` for some other purpose.
    pub fn request_id(&self) -> Option<i32> {
        let kind = self.message_type();
        if !routes_by_request_id(kind) {
            return None;
        }
        if let Some(raw) = self.raw_bytes() {
            let env: ProtoIdEnvelope = prost::Message::decode(raw).ok()?;
            env.id
        } else {
            self.peek_int(text_request_id_field(kind)?).ok()
        }
    }

    /// Try to extract the order id from the message.
    ///
    /// Every `order_id`-bearing message type (`OpenOrder`, `OrderStatus`,
    /// `ExecutionData`, `ExecutionDataEnd`) is proto-framed. Three carry
    /// `order_id` at proto tag 1 (decoded via the minimal [`ProtoIdEnvelope`]);
    /// `ExecutionData` nests it under `execution.order_id` and uses
    /// [`ExecutionDetailsMinimal`] to skip the `contract` sub-message.
    pub fn order_id(&self) -> Option<i32> {
        let raw = self.raw_bytes()?;
        match self.message_type() {
            IncomingMessages::OpenOrder | IncomingMessages::OrderStatus | IncomingMessages::ExecutionDataEnd => {
                prost::Message::decode(raw).ok().and_then(|e: ProtoIdEnvelope| e.id)
            }
            IncomingMessages::ExecutionData => {
                let p: ExecutionDetailsMinimal = prost::Message::decode(raw).ok()?;
                p.execution.and_then(|e| e.order_id)
            }
            _ => None,
        }
    }

    /// Try to extract the execution id from the message.
    ///
    /// `ExecutionData` nests `exec_id` under `execution.exec_id`;
    /// `CommissionsReport` carries it at the top level. Both arrive
    /// proto-framed.
    pub fn execution_id(&self) -> Option<String> {
        let raw = self.raw_bytes()?;
        match self.message_type() {
            IncomingMessages::ExecutionData => {
                let p: ExecutionDetailsMinimal = prost::Message::decode(raw).ok()?;
                p.execution.and_then(|e| e.exec_id)
            }
            IncomingMessages::CommissionsReport => {
                let p: crate::proto::CommissionAndFeesReport = prost::Message::decode(raw).ok()?;
                p.exec_id
            }
            _ => None,
        }
    }

    /// Peek an integer field without advancing the cursor. Called from
    /// [`Self::request_id`]'s text-fallback path (tests only at floor 213)
    /// and the handshake parser (pre-proto framing).
    ///
    /// Refuses proto-framed messages defensively (per docs/rules/wire/proto-aware-accessors.md):
    /// if `raw_bytes()` is `Some`, the caller picked the wrong accessor —
    /// they should be decoding the proto envelope, not reading a text-field
    /// index. Production callers (`request_id`, handshake) already gate on
    /// `raw_bytes().is_none()` so this guard is unreachable from them.
    ///
    /// This is [`Self::require_proto`]'s mirror image, and returns the same
    /// `Error::UnexpectedWireFormat` — a framing mismatch is never the
    /// skippable `UnexpectedResponse`, in either direction.
    pub fn peek_int(&self, i: usize) -> Result<i32, Error> {
        if self.raw_bytes().is_some() {
            return Err(Error::unexpected_wire_format(self));
        }
        if i >= self.fields.len() {
            return Err(Error::eof_at(i, "int"));
        }

        let field = &self.fields[i];
        match field.parse() {
            Ok(val) => Ok(val),
            Err(err) => Err(Error::Parse(i, field.into(), err.to_string())),
        }
    }

    /// Consume and parse the next integer field.
    pub fn next_int(&mut self) -> Result<i32, Error> {
        if self.i >= self.fields.len() {
            return Err(Error::eof_at(self.i, "int"));
        }

        let field = &self.fields[self.i];
        self.i += 1;

        match field.parse() {
            Ok(val) => Ok(val),
            Err(err) => Err(Error::Parse(self.i, field.into(), err.to_string())),
        }
    }

    /// Consume the next field as a string.
    pub fn next_string(&mut self) -> Result<String, Error> {
        if self.i >= self.fields.len() {
            return Err(Error::eof_at(self.i, "string"));
        }

        let field = &self.fields[self.i];
        self.i += 1;
        Ok(String::from(field))
    }

    /// Consume and parse the next floating-point field. Test-only symmetry
    /// with [`Self::next_int`] / [`Self::next_string`] — production code no
    /// longer reads doubles from text-framed messages at floor 213.
    #[cfg(test)]
    pub fn next_double(&mut self) -> Result<f64, Error> {
        if self.i >= self.fields.len() {
            return Err(Error::eof_at(self.i, "double"));
        }

        let field = &self.fields[self.i];
        self.i += 1;

        if field.is_empty() || field == "0" || field == "0.0" {
            return Ok(0.0);
        }

        match field.parse() {
            Ok(val) => Ok(val),
            Err(err) => Err(Error::Parse(self.i, field.into(), err.to_string())),
        }
    }

    /// Build a response message from a NUL-delimited payload.
    pub fn from(fields: &str) -> ResponseMessage {
        ResponseMessage::from_text_fields(fields.split_terminator('\x00').map(|x| x.to_string()).collect())
    }

    /// Text frames keep the discriminant as `fields[0]` — the handshake reader
    /// walks the field cursor from index 0 — so `kind` is derived from it here
    /// rather than replacing it.
    pub(crate) fn from_text_fields(fields: Vec<String>) -> ResponseMessage {
        let message_id = fields.first().and_then(|id| i32::from_str(id).ok());
        Self::new(message_id, fields, None)
    }

    #[cfg(test)]
    /// Build a response message from a pipe-delimited payload (test helper).
    pub fn from_simple(fields: &str) -> ResponseMessage {
        ResponseMessage::from_text_fields(fields.split_terminator('|').map(|x| x.to_string()).collect())
    }

    /// Encode the message back into a NUL-delimited string.
    pub fn encode(&self) -> String {
        let mut data = self.fields.join("\0");
        data.push('\0');
        data
    }

    #[cfg(test)]
    /// Serialize the message into a pipe-delimited format (test helper).
    pub fn encode_simple(&self) -> String {
        let mut data = self.fields.join("|");
        data.push('|');
        data
    }
}

/// An error message from the TWS API.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct Notice {
    /// Request or order ID that originated the notice.
    /// `None` for request-less notices.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub request_id: Option<i32>,
    /// Error code reported by TWS.
    pub code: i32,
    /// Human-readable error message text.
    pub message: String,
    /// Timestamp when the error occurred.
    /// Only present for server versions >= ERROR_TIME (194).
    pub error_time: Option<OffsetDateTime>,
    /// Advanced order-reject JSON payload, present on hard order-rejection
    /// notices for server versions >= ADVANCED_ORDER_REJECT. Empty otherwise.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub advanced_order_reject_json: String,
}

/// Error code indicating an order was cancelled (confirmation, not an error).
pub const ORDER_CANCELLED_CODE: i32 = 202;

/// Generic order-message code whose text determines whether TWS reports a warning or an error.
pub const ORDER_MESSAGE_CODE: i32 = 399;

/// "Market depth data has been RESET". A [`DATA_ADVISORY_CODES`] entry; a
/// depth subscription yields it as [`MarketDepths::Reset`](crate::market_data::realtime::MarketDepths::Reset).
pub(crate) const MARKET_DEPTH_RESET_CODE: i32 = 317;

/// "Historical Market Data Service query message". Classified `Error`, but a
/// scanner subscription keeps its "no items retrieved" form nonterminal; see
/// [`classify`].
pub(crate) const HMDS_QUERY_MESSAGE_CODE: i32 = 165;

/// Range of error codes that are considered warnings: the whole `21xx` band.
///
/// IB's published table stops at 2169, but the gateway keeps adding codes above
/// it (2176, the fractional-share size-rule warning; 2187, generic ticks
/// unavailable on delayed-data fallback), and a ceiling of 2169 turned each new
/// one into a hard error that failed in-flight one-shots and ended
/// subscriptions.
pub const WARNING_CODE_RANGE: std::ops::RangeInclusive<i32> = 2100..=2199;

/// Code 0 is a code-less frame: IB Gateway omits `error_code` on informational
/// notices (e.g. "Warning: Approaching max rate of 50 messages per second"),
/// and the absent field decodes to 0. An error frame that fails proto decode
/// falls back to the same default, so code 0 never carries a hard error.
pub(crate) fn is_warning_message(code: i32, message: &str) -> bool {
    code == 0
        || WARNING_CODE_RANGE.contains(&code)
        || (code == ORDER_MESSAGE_CODE && message.lines().any(|line| line.trim_start().starts_with("Warning:")))
}

/// Classify a raw error frame into a disjoint [`NoticeCategory`].
///
/// The single owner of the precedence chain documented on [`NoticeCategory`];
/// [`Notice::category`] and [`is_informational_code`] both derive from it, so
/// routing and the public partition cannot disagree.
///
/// One exception sits downstream of routing:
/// [`StreamDecoder::is_nonterminal_notice`](crate::subscriptions::common::StreamDecoder::is_nonterminal_notice)
/// lets a subscription deliver a request-bound `Error` notice as
/// `SubscriptionItem::Notice` instead of ending. The notice keeps its `Error`
/// category. Only the scanner uses it, for [`HMDS_QUERY_MESSAGE_CODE`] "no items
/// retrieved" (#886); making 165 informational here would also reach one-shot
/// requests, which would wait for an answer that never comes.
pub(crate) fn classify(code: i32, message: &str) -> NoticeCategory {
    if code == ORDER_CANCELLED_CODE {
        NoticeCategory::Cancellation
    } else if DATA_ADVISORY_CODES.contains(&code) {
        NoticeCategory::DataAdvisory
    } else if is_warning_message(code, message) {
        NoticeCategory::Warning
    } else if SYSTEM_MESSAGE_CODES.contains(&code) {
        NoticeCategory::SystemMessage
    } else if REQUEST_ERROR_CODES.contains(&code) {
        NoticeCategory::RequestError
    } else if ORDER_REJECTION_CODE_RANGE.contains(&code) {
        NoticeCategory::OrderRejection
    } else {
        NoticeCategory::Error
    }
}

/// Check if an error code is informational: every [`NoticeCategory`] except
/// `RequestError`, `OrderRejection` and `Error`.
///
/// For these TWS proceeds with the request, the frame confirms an outcome the
/// caller asked for, or the frame reports a connection-wide state change
/// rather than a failed request — so they are routed as a `Notice` rather
/// than terminating the subscription as an `Error`, and, when request-less,
/// they do not fail the pending one-shots.
///
/// System messages never stand in for a per-request answer: after 1100 TWS
/// still answers or rejects each request itself, and after 1300 the socket is
/// dropped, so pending one-shots see `Error::ConnectionReset` from the
/// transport reset and retry. Note 202 and the system codes are deliberately
/// *not* in [`is_warning_message`]: `Notice::is_warning()` stays false for
/// them; only the routing disposition treats them like warnings.
pub(crate) fn is_informational_code(code: i32, message: &str) -> bool {
    // Exhaustive on purpose: a new `NoticeCategory` variant must decide its
    // routing disposition here, not inherit one from a wildcard.
    match classify(code, message) {
        NoticeCategory::Cancellation | NoticeCategory::DataAdvisory | NoticeCategory::Warning | NoticeCategory::SystemMessage => true,
        NoticeCategory::RequestError | NoticeCategory::OrderRejection | NoticeCategory::Error => false,
    }
}

/// Connectivity between IB and TWS has been lost.
pub(crate) const CONNECTIVITY_LOST_CODE: i32 = 1100;
/// Connectivity restored, but market data was lost; resubscription is required.
pub(crate) const CONNECTIVITY_RESTORED_DATA_LOST_CODE: i32 = 1101;
/// Connectivity restored with market data maintained (nothing lost).
pub(crate) const CONNECTIVITY_RESTORED_DATA_MAINTAINED_CODE: i32 = 1102;
/// Socket port was reset during an active connection; the connection is dropped.
pub(crate) const SOCKET_PORT_RESET_CODE: i32 = 1300;

/// System message codes indicating connectivity status.
/// - 1100: Connectivity lost
/// - 1101: Connectivity restored, market data lost (resubscribe needed)
/// - 1102: Connectivity restored, market data maintained
/// - 1300: Socket port reset during active connection
pub const SYSTEM_MESSAGE_CODES: [i32; 4] = [
    CONNECTIVITY_LOST_CODE,
    CONNECTIVITY_RESTORED_DATA_LOST_CODE,
    CONNECTIVITY_RESTORED_DATA_MAINTAINED_CODE,
    SOCKET_PORT_RESET_CODE,
];

/// Data-advisory codes: frames that look like errors but reject nothing — the
/// request stands and data keeps flowing. Each one describes what will arrive
/// (a fallback, a partial entitlement, or a reset of what was already
/// delivered), so they are informational notices, not errors. Classifying them
/// as errors would terminate the subscription before its data arrives.
/// - 317: Market depth data has been RESET. Please empty deep book contents
///   before applying any new entries. A depth subscription yields it as
///   [`MarketDepths::Reset`](crate::market_data::realtime::MarketDepths::Reset).
/// - 2188: Up-to-the-second historical data requires additional subscription for the API.
/// - 10089: Requested market data requires additional subscription for API; delayed market data is available.
/// - 10090: Part of requested market data is not subscribed. Subscription-independent ticks are still active.
/// - 10091: Part of requested market data requires additional subscription for API.
/// - 10167: Requested market data is not subscribed. Displaying delayed market data.
///
/// A slice rather than an array so that adding a code is not a type change
/// for callers that bind the constant explicitly.
pub const DATA_ADVISORY_CODES: &[i32] = &[MARKET_DEPTH_RESET_CODE, 2188, 10089, 10090, 10091, 10167];

/// Request-error codes inside [`ORDER_REJECTION_CODE_RANGE`]: a request other
/// than an order failed (market data, depth, historical data, scanner, session
/// setup). Classified [`NoticeCategory::RequestError`], ahead of the band.
///
/// Only codes that never answer an order are listed. Codes that answer both
/// orders and other requests stay [`NoticeCategory::OrderRejection`], so
/// [`Notice::is_order_rejection`] keeps matching them on order streams: 200 (no
/// security definition) and 320-323 (server error reading, validating or
/// processing a request; 320 answers an invalid attached order, #842).
/// - 300: Can't find EId with ticker Id (cancelling unknown market data).
/// - 301, 302: Invalid ticker action; error parsing stop ticker string.
/// - 309: Max number of market depth requests has been reached.
/// - 310: Can't find the subscribed market depth.
/// - 316: Market depth data has been HALTED. Please re-subscribe.
/// - 319: Invalid log level.
/// - 326: Client id already in use.
/// - 327: Only clientId 0 can set the auto bind TWS orders property.
/// - 330, 331: Managed accounts list needs an FA or STL account with managed accounts.
/// - 354: Not subscribed to requested market data.
/// - 357: Client version out of date.
/// - 365, 366: No scanner subscription / historical data query for the ticker id.
/// - 385, 386: Duplicate ticker id for scanner subscription / historical data query.
///
/// A slice rather than an array so that adding a code is not a type change
/// for callers that bind the constant explicitly.
pub const REQUEST_ERROR_CODES: &[i32] = &[300, 301, 302, 309, 310, 316, 319, 326, 327, 330, 331, 354, 357, 365, 366, 385, 386];

/// Data-farm codes reporting a healthy connection ("…connection is OK").
/// Subset of [`WARNING_CODE_RANGE`]; classified [`ConnectivityStatus::Ok`].
pub(crate) const FARM_OK_CODES: [i32; 3] = [2104, 2106, 2158];

/// Data-farm codes reporting a broken connection ("…connection is broken").
/// Subset of [`WARNING_CODE_RANGE`]; classified [`ConnectivityStatus::Broken`].
pub(crate) const FARM_BROKEN_CODES: [i32; 3] = [2103, 2105, 2157];

/// Data-farm codes reporting a dormant-but-available connection
/// ("…inactive but should be available upon demand").
/// Subset of [`WARNING_CODE_RANGE`]; classified [`ConnectivityStatus::Inactive`].
pub(crate) const FARM_INACTIVE_CODES: [i32; 2] = [2107, 2108];

/// Data-farm codes reporting a connection in progress ("…farm is connecting").
/// Subset of [`WARNING_CODE_RANGE`]; classified [`ConnectivityStatus::Connecting`].
pub(crate) const FARM_CONNECTING_CODES: [i32; 1] = [2119];

/// The order-rejection band (200-399): order parameter validation, margin and
/// risk-check rejections.
///
/// [`Notice::category`] classifies a code in this band as
/// [`NoticeCategory::OrderRejection`] unless an earlier rule claims it; see
/// [`NoticeCategory`] for the precedence chain.
pub const ORDER_REJECTION_CODE_RANGE: std::ops::RangeInclusive<i32> = 200..=399;

/// Synthesized notice code emitted when a handshake-time frame's recognized
/// [`IncomingMessages`] kind has no typed `StartupMessage` variant. A frame
/// whose id maps to no kind at all raises [`UNKNOWN_MESSAGE_TYPE_CODE`]
/// instead, as it does after the handshake. Negative
/// (TWS uses 0+); the other client-synthesized codes are
/// [`HANDSHAKE_DECODE_FAILURE_CODE`], [`UNKNOWN_MESSAGE_TYPE_CODE`],
/// [`SUBSCRIPTION_LAG_CODE`], [`NOTICE_STREAM_LAG_CODE`], and
/// [`TRANSPORT_RECONNECT_CODE`]. See
/// [`Notice::is_handshake_synthetic`].
pub const HANDSHAKE_UNKNOWN_FRAME_CODE: i32 = -3;

/// Synthesized notice code emitted when a typed handshake decoder fails for
/// a known [`IncomingMessages`] kind (`OpenOrder`, `OrderStatus`,
/// `AccountValue`/`PortfolioValue`/`AccountUpdateTime`/`AccountDownloadEnd`,
/// `ExecutionData`, `CommissionsReport`, `CompletedOrder`). Distinct from
/// [`HANDSHAKE_UNKNOWN_FRAME_CODE`] so consumers can separate TWS schema
/// drift from rust-ibapi decoder bugs. See
/// [`Notice::is_handshake_synthetic`].
pub const HANDSHAKE_DECODE_FAILURE_CODE: i32 = -4;

/// Synthesized notice code emitted when a frame arrives whose 4-byte message
/// id maps to no known [`IncomingMessages`] kind, so nothing can route it.
///
/// Negative, like the other client-synthesized notice codes
/// ([`HANDSHAKE_UNKNOWN_FRAME_CODE`], [`HANDSHAKE_DECODE_FAILURE_CODE`],
/// [`SUBSCRIPTION_LAG_CODE`], [`NOTICE_STREAM_LAG_CODE`],
/// [`TRANSPORT_RECONNECT_CODE`]); TWS itself only
/// uses codes 0 and up.
///
/// This is the observable form of a framing desynchronization: the length
/// prefix is positional, so once a read starts at the wrong offset every
/// subsequent message id is garbage — usually unrecognized (this notice), but
/// occasionally colliding with a real kind, in which case the payload decodes
/// without error into plausible-looking wrong values.
///
/// The notice text names the offending id, which is what separates the two
/// explanations: a slipped stream yields *scattered* ids, while a message type
/// IBKR has added repeats one. A burst of distinct ids on a previously healthy
/// connection means the framing slipped.
///
/// Raised the same way during the connection handshake, which is the window a
/// reconnect runs through; [`HANDSHAKE_UNKNOWN_FRAME_CODE`] is reserved for
/// recognized kinds with no typed startup variant.
pub const UNKNOWN_MESSAGE_TYPE_CODE: i32 = -5;

/// Build the [`UNKNOWN_MESSAGE_TYPE_CODE`] notice for `message`, and emit the
/// matching `warn!`. The single owner of the wording, shared by steady-state
/// routing and the handshake.
pub(crate) fn unknown_message_type_notice(message: &ResponseMessage) -> Notice {
    // The Debug dump already carries the id; the notice has no such fallback,
    // so it interpolates.
    log::warn!("unroutable frame: message id maps to no known type — the stream may be desynchronized: {message:?}");
    let id = match message.message_id() {
        Some(id) => format!("message id {id}"),
        None => "no message id".to_string(),
    };
    Notice::synthesized(
        UNKNOWN_MESSAGE_TYPE_CODE,
        format!("received a frame with {id}, which maps to no known type; the stream may be desynchronized"),
    )
}

/// Synthesized notice code emitted in-band on an async subscription whose
/// consumer fell behind its broadcast channel: the channel evicted the oldest
/// frames, and this notice — carrying the dropped count in its message — is
/// what the consumer sees in their place.
///
/// Negative, like the other client-synthesized notice codes; TWS itself only
/// uses codes 0 and up.
///
/// On receiving this notice the stream is still live, but frames are gone:
/// reconcile the same way as after a reconnect gap.
///
/// - **Market data and other non-order streams** (ticks, bars, depth,
///   positions, account updates, PnL, news, contract details): bounded and
///   lossy by design — freshness beats completeness, and a feed
///   self-corrects with the next tick. Channels hold
///   `ClientBuilder::channel_capacity` frames; a consumer that lags
///   persistently should raise it or consume faster.
/// - **Orders** (`place_order`, `cancel_order`, `exercise_options`,
///   `executions`, `order_update_stream`, the open/completed-order streams):
///   `channel_capacity` can raise these channels but not shrink them, so
///   this notice there means order state was lost and the client logs it as
///   an error. Resynchronize with `open_orders()` / `executions()` before
///   acting on recorded state.
///
/// The sync client never drops: its queues are unbounded and log a warning
/// at every 10,000 unread messages instead. Both transports surface falling
/// behind; only async trades completeness for bounded memory.
pub const SUBSCRIPTION_LAG_CODE: i32 = -6;

/// Build the in-band notice for a subscription that fell behind its broadcast
/// channel and had `skipped` frames evicted, and emit the matching `warn!`.
/// The single owner of the non-order lag wording; see [`SUBSCRIPTION_LAG_CODE`].
#[cfg(feature = "async")]
pub(crate) fn subscription_lag_notice(skipped: u64) -> Notice {
    let message = format!("subscription fell behind; {skipped} frames dropped (consumer lagged broadcast channel)");
    log::warn!("{message}");
    Notice::synthesized(SUBSCRIPTION_LAG_CODE, message)
}

/// [`subscription_lag_notice`] for an order-class channel, where a gap means
/// lost order state: logged as an error, and the message says to resync.
/// The single owner of the order lag wording.
#[cfg(feature = "async")]
pub(crate) fn order_lag_notice(skipped: u64) -> Notice {
    let message = format!("order stream fell behind; {skipped} frames dropped — order state unknown, resync with open_orders() / executions()");
    log::error!("{message}");
    Notice::synthesized(SUBSCRIPTION_LAG_CODE, message)
}

/// Synthesized notice code delivered in-band on the notice stream when its
/// consumer fell behind the notice fan-out: the broadcast channel evicted the
/// oldest notices, and this notice — carrying the dropped count in its
/// message — is what the consumer sees in their place.
///
/// Negative, like the other client-synthesized notice codes; TWS itself only
/// uses codes 0 and up.
///
/// The notice stream is how a stateful consumer receives the unrouted
/// connection-status notices (1100 lost, 1101/1102 restored) it derives
/// durable conclusions from, so a silent skip is not survivable: losing a
/// 1101 voids every market-data request server-side yet leaves the client's
/// subscriptions looking healthy forever, and losing a restoration notice
/// after a recorded 1100 holds every pending reopen forever. On receiving
/// this notice the stream's conclusions are unknown — any of them may rest
/// on notices that were dropped — so the consumer must resynchronize rather
/// than resume: treat recorded state as describing an unknown moment between
/// the eviction and now, and re-derive it (a connection-state authority
/// re-baselines its link state and re-establishes subscriptions). This is
/// the notice-stream instance of [`SUBSCRIPTION_LAG_CODE`], closing the
/// step-1 leftover of #779. The sync
/// notice fan-out is unbounded and cannot lag; it logs a warning at every
/// 10,000 unread notices instead.
pub const NOTICE_STREAM_LAG_CODE: i32 = -7;

/// Build the in-band notice delivered when the notice stream's consumer fell
/// behind the notice fan-out and `skipped` notices were evicted, and emit the
/// matching `warn!`. The single owner of the notice-stream lag wording; see
/// [`NOTICE_STREAM_LAG_CODE`].
#[cfg(feature = "async")]
pub(crate) fn notice_stream_lag_notice(skipped: u64) -> Notice {
    let message = format!("notice stream fell behind; {skipped} notices dropped (consumer lagged the notice fan-out)");
    log::warn!("{message}");
    Notice::synthesized(NOTICE_STREAM_LAG_CODE, message)
}

/// Synthesized notice code published to the notice stream (sync and async)
/// after the transport finishes reconnecting its socket to TWS/Gateway: a new
/// connection whose server-side state starts empty, so every request
/// subscription made on the previous connection is gone, and unrouted-notice
/// state — notably the 1100/1101/1102 connection-status sequence — describes
/// the previous connection only.
///
/// Negative, like the other client-synthesized notice codes; TWS itself only
/// uses codes 0 and up.
///
/// TWS never frames this event itself: 1101/1102 announce the restoration
/// *transition* to clients connected at that moment and are not replayed to a
/// client that connects afterwards, so a consumer that recorded 1100 ("TWS
/// lost its IB-server link") before a socket drop cannot learn from the new
/// connection that the link is back. On receiving this notice, treat every
/// fact gathered from the previous connection as describing that connection
/// alone: re-establish what the new session must provide (resubscribe
/// requests), and reset connection-state conclusions — a recorded 1100 — to
/// the fresh-connection baseline a new client starts from, then let the new
/// connection's own notices re-derive the link state.
///
/// Published once the reconnected session is live: the channel reset runs
/// before the reconnect, so a consumer may resubscribe from inside its handler
/// and land on the new session without racing either. Like the other
/// client-synthesized codes this classifies as [`NoticeCategory::Error`]
/// ("everything else"); consumers match the constant itself rather than the
/// category.
pub const TRANSPORT_RECONNECT_CODE: i32 = -8;

/// Build the [`TRANSPORT_RECONNECT_CODE`] notice. Emits no log line: the
/// transport already logs the reconnect. The single owner of the wording.
pub(crate) fn transport_reconnect_notice() -> Notice {
    Notice::synthesized(
        TRANSPORT_RECONNECT_CODE,
        "transport reconnected to TWS/Gateway; this is a new connection whose server-side state starts empty, so every request subscription from the previous connection is gone".to_string(),
    )
}

/// Typed classification of a [`Notice`] by TWS error-code range.
///
/// Returned by [`Notice::category`]. Forms a disjoint partition over all
/// possible notices; when classifications overlap on the wire, the classifier
/// resolves overlap by **precedence**:
///
/// 1. [`Cancellation`](Self::Cancellation) — exact code 202.
/// 2. [`DataAdvisory`](Self::DataAdvisory) — [`DATA_ADVISORY_CODES`]. Ahead of
///    the ranges: 317 is inside [`ORDER_REJECTION_CODE_RANGE`] and 2188 inside
///    [`WARNING_CODE_RANGE`].
/// 3. [`Warning`](Self::Warning) — [`WARNING_CODE_RANGE`], code 399 with a `Warning:`
///    line, or code 0 (a frame whose `error_code` field was absent on the wire).
/// 4. [`SystemMessage`](Self::SystemMessage) — 1100, 1101, 1102, 1300.
/// 5. [`RequestError`](Self::RequestError) — [`REQUEST_ERROR_CODES`]. Ahead of
///    [`ORDER_REJECTION_CODE_RANGE`], which they sit inside.
/// 6. [`OrderRejection`](Self::OrderRejection) — [`ORDER_REJECTION_CODE_RANGE`],
///    excluding the cases above.
/// 7. [`Error`](Self::Error) — everything else.
///
/// Each `Notice::is_*` category predicate ([`Notice::is_cancellation`],
/// [`Notice::is_warning`], ...) is `category() == X` for its variant `X`, so the
/// predicates are disjoint too.
///
/// Marked `#[non_exhaustive]` so IBKR can introduce new code ranges without a
/// breaking release.
///
/// # Examples
///
/// ```no_run
/// use ibapi::{Notice, NoticeCategory};
/// # let notice: Notice = unimplemented!();
/// match notice.category() {
///     NoticeCategory::OrderRejection => eprintln!("rejected: {}", notice),
///     NoticeCategory::RequestError   => eprintln!("failed: {}",   notice),
///     NoticeCategory::Warning        => eprintln!("warn: {}",     notice),
///     NoticeCategory::Error          => eprintln!("error: {}",    notice),
///     _ => {}
/// }
/// ```
#[non_exhaustive]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum NoticeCategory {
    /// Order cancellation confirmation (exact code 202).
    Cancellation,
    /// Informational warning ([`WARNING_CODE_RANGE`], code 399 with a `Warning:`
    /// line, or code 0 — a code-less frame).
    Warning,
    /// Connectivity / system status (codes 1100, 1101, 1102, 1300).
    SystemMessage,
    /// Order rejection ([`ORDER_REJECTION_CODE_RANGE`], excluding the cases
    /// above it in the precedence chain).
    OrderRejection,
    /// A request other than an order failed ([`REQUEST_ERROR_CODES`]): market
    /// data, depth, historical data, scanner, session setup. Terminal.
    RequestError,
    /// Data advisory ([`DATA_ADVISORY_CODES`]): the request is not rejected and
    /// data follows — a fallback, a partial entitlement, or a depth-book reset.
    /// Informational.
    DataAdvisory,
    /// Any other error code.
    Error,
}

/// Connectivity sub-state of a data-farm notice within [`WARNING_CODE_RANGE`].
///
/// Returned by [`Notice::connectivity_status`] (and [`ConnectivityStatus::from_code`]
/// for a raw code) for the data-farm status codes; `None` for every other notice.
/// Lets reconnect/health logic tell "farm came back online" from "farm went
/// inactive" without re-parsing codes. Additive to [`NoticeCategory`], which still
/// classifies all of [`WARNING_CODE_RANGE`] as [`NoticeCategory::Warning`]
/// (bar the advisory 2188).
///
/// The code→state vocabulary follows IB's published Message Codes table:
///
/// | State | Codes | Wire meaning |
/// |---|---|---|
/// | [`Ok`](Self::Ok) | 2104, 2106, 2158 | …data farm connection is OK |
/// | [`Broken`](Self::Broken) | 2103, 2105, 2157 | …data farm connection is broken |
/// | [`Inactive`](Self::Inactive) | 2107, 2108 | …connection is inactive but should be available upon demand |
/// | [`Connecting`](Self::Connecting) | 2119 | …data farm is connecting |
///
/// The variant set is closed: an unrecognized code classifies as `None`
/// (via [`ConnectivityStatus::from_code`]), not a new variant — so callers can
/// match exhaustively and handle unknowns through the `Option`.
///
/// # Examples
///
/// ```no_run
/// use ibapi::{Notice, ConnectivityStatus};
/// # let notice: Notice = unimplemented!();
/// match notice.connectivity_status() {
///     Some(ConnectivityStatus::Ok)         => {/* farm healthy */}
///     Some(ConnectivityStatus::Broken)     => {/* link down */}
///     Some(ConnectivityStatus::Inactive)   => {/* dormant, available on demand */}
///     Some(ConnectivityStatus::Connecting) => {/* reconnecting */}
///     None => {/* not a data-farm notice */}
/// }
/// ```
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ConnectivityStatus {
    /// Data-farm connection is OK.
    Ok,
    /// Data-farm connection is broken.
    Broken,
    /// Connection inactive but available upon demand.
    Inactive,
    /// Connection is in the process of connecting.
    Connecting,
}

impl ConnectivityStatus {
    /// Classify a raw TWS error code into a data-farm connectivity sub-state.
    ///
    /// Returns `Some(..)` for the data-farm status codes inside
    /// [`WARNING_CODE_RANGE`]; `None` for every other code. Use this when you
    /// hold a raw code; use [`Notice::connectivity_status`] when you hold a
    /// [`Notice`].
    ///
    /// # Examples
    ///
    /// ```
    /// use ibapi::ConnectivityStatus;
    /// assert_eq!(ConnectivityStatus::from_code(2104), Some(ConnectivityStatus::Ok));
    /// assert_eq!(ConnectivityStatus::from_code(2105), Some(ConnectivityStatus::Broken));
    /// assert_eq!(ConnectivityStatus::from_code(500), None);
    /// ```
    pub fn from_code(code: i32) -> Option<ConnectivityStatus> {
        if FARM_OK_CODES.contains(&code) {
            Some(ConnectivityStatus::Ok)
        } else if FARM_BROKEN_CODES.contains(&code) {
            Some(ConnectivityStatus::Broken)
        } else if FARM_INACTIVE_CODES.contains(&code) {
            Some(ConnectivityStatus::Inactive)
        } else if FARM_CONNECTING_CODES.contains(&code) {
            Some(ConnectivityStatus::Connecting)
        } else {
            None
        }
    }
}

impl From<&ResponseMessage> for Notice {
    /// Build a Notice from a protobuf Error frame; at floor 213 every Error
    /// payload arrives proto-encoded. Returns `Notice::from(DecodedError::default())`
    /// (empty / code 0) if the proto bytes are absent or undecodable.
    fn from(message: &ResponseMessage) -> Notice {
        let payload = message
            .raw_bytes()
            .and_then(crate::transport::routing::decode_error_envelope)
            .unwrap_or_default();
        Notice::from(payload)
    }
}

impl Notice {
    /// Build a client-synthesized notice with no wire timestamp and no
    /// advanced-order-reject JSON. Used by the client-side observability
    /// codes (see [`HANDSHAKE_UNKNOWN_FRAME_CODE`],
    /// [`HANDSHAKE_DECODE_FAILURE_CODE`], [`UNKNOWN_MESSAGE_TYPE_CODE`],
    /// [`SUBSCRIPTION_LAG_CODE`], [`NOTICE_STREAM_LAG_CODE`],
    /// [`TRANSPORT_RECONNECT_CODE`]).
    pub(crate) fn synthesized(code: i32, message: String) -> Notice {
        Notice {
            request_id: None,
            code,
            message,
            error_time: None,
            advanced_order_reject_json: String::new(),
        }
    }

    /// Returns `true` if this notice indicates an order was cancelled (code 202).
    ///
    /// Code 202 is sent by TWS to confirm an order cancellation. This is an
    /// informational message, not an error.
    pub fn is_cancellation(&self) -> bool {
        self.category() == NoticeCategory::Cancellation
    }

    /// Returns `true` if this is a warning message.
    ///
    /// Warnings are [`WARNING_CODE_RANGE`], code 399 with a `Warning:` line, and
    /// code 0 — a frame whose `error_code` field was absent on the wire, which
    /// IB Gateway sends for informational notices. Same as
    /// `category() == NoticeCategory::Warning`.
    pub fn is_warning(&self) -> bool {
        self.category() == NoticeCategory::Warning
    }

    /// Returns `true` if this is a system/connectivity message (codes 1100-1102, 1300).
    ///
    /// System messages indicate connectivity status changes:
    /// - 1100: Connectivity between IB and TWS lost
    /// - 1101: Connectivity restored, market data lost (resubscribe needed)
    /// - 1102: Connectivity restored, market data maintained
    /// - 1300: Socket port reset during active connection
    pub fn is_system_message(&self) -> bool {
        self.category() == NoticeCategory::SystemMessage
    }

    /// Returns `true` if this is a data advisory ([`DATA_ADVISORY_CODES`]).
    ///
    /// Data advisories reject nothing: the request stands and data follows —
    /// a fallback, a partial entitlement, or a depth-book reset. The
    /// subscription stays open and the notice is informational, not an error.
    /// This does not guarantee that every requested field will arrive.
    pub fn is_data_advisory(&self) -> bool {
        self.category() == NoticeCategory::DataAdvisory
    }

    /// Returns `true` if this is an informational notice (not an error).
    ///
    /// Informational notices include cancellation confirmations, warnings,
    /// system/connectivity messages, and data advisories.
    ///
    /// A scanner subscription also yields TWS code 165 "no items retrieved"
    /// (an empty scan) as a `SubscriptionItem::Notice` and stays open, although
    /// that notice is not informational; don't end a scanner loop on
    /// `!is_informational()` alone.
    pub fn is_informational(&self) -> bool {
        is_informational_code(self.code, &self.message)
    }

    /// Returns `true` if this is an error requiring attention.
    ///
    /// Returns `false` for informational messages like cancellation confirmations,
    /// warnings, and system messages.
    pub fn is_error(&self) -> bool {
        !self.is_informational()
    }

    /// Returns `true` if this notice is an order rejection
    /// ([`NoticeCategory::OrderRejection`]).
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use ibapi::Notice;
    /// # let notice: Notice = unimplemented!();
    /// if notice.is_order_rejection() {
    ///     eprintln!("rejection: {}", notice);
    /// }
    /// ```
    pub fn is_order_rejection(&self) -> bool {
        self.category() == NoticeCategory::OrderRejection
    }

    /// Returns `true` if a request other than an order failed
    /// ([`REQUEST_ERROR_CODES`], [`NoticeCategory::RequestError`]).
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use ibapi::Notice;
    /// # let notice: Notice = unimplemented!();
    /// if notice.is_request_error() {
    ///     eprintln!("request failed: {}", notice);
    /// }
    /// ```
    pub fn is_request_error(&self) -> bool {
        self.category() == NoticeCategory::RequestError
    }

    /// Returns `true` if this notice was synthesized client-side during the
    /// connection handshake — i.e. carries either
    /// [`HANDSHAKE_UNKNOWN_FRAME_CODE`] (a recognized `IncomingMessages` kind with no
    /// typed `StartupMessage` variant) or [`HANDSHAKE_DECODE_FAILURE_CODE`]
    /// (a typed decoder failed on a known kind).
    ///
    /// Subscribers to [`Client::notice_stream`](crate::Client::notice_stream)
    /// can use this to log + investigate without conflating with TWS-emitted
    /// notices.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use ibapi::Notice;
    /// # let notice: Notice = unimplemented!();
    /// if notice.is_handshake_synthetic() {
    ///     eprintln!("handshake observability: code={} {}", notice.code, notice);
    /// }
    /// ```
    pub fn is_handshake_synthetic(&self) -> bool {
        self.code == HANDSHAKE_UNKNOWN_FRAME_CODE || self.code == HANDSHAKE_DECODE_FAILURE_CODE
    }

    /// Returns `true` if rust-ibapi synthesized this notice rather than
    /// receiving it from TWS: any negative code. TWS uses codes 0 and up.
    ///
    /// Covers [`HANDSHAKE_UNKNOWN_FRAME_CODE`], [`HANDSHAKE_DECODE_FAILURE_CODE`],
    /// [`UNKNOWN_MESSAGE_TYPE_CODE`], [`SUBSCRIPTION_LAG_CODE`],
    /// [`NOTICE_STREAM_LAG_CODE`] and [`TRANSPORT_RECONNECT_CODE`], and any
    /// code added later. These all classify as [`NoticeCategory::Error`], so
    /// use this predicate or the constants, not [`Notice::category`], to tell
    /// them apart from TWS errors.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use ibapi::Notice;
    /// # let notice: Notice = unimplemented!();
    /// if notice.is_client_synthesized() {
    ///     eprintln!("client-side condition: code={} {}", notice.code, notice);
    /// }
    /// ```
    pub fn is_client_synthesized(&self) -> bool {
        self.code < 0
    }

    /// Classify this notice into a disjoint [`NoticeCategory`].
    ///
    /// See [`NoticeCategory`] for the precedence chain.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use ibapi::{Notice, NoticeCategory};
    /// # let notice: Notice = unimplemented!();
    /// let kind = match notice.category() {
    ///     NoticeCategory::Cancellation
    ///     | NoticeCategory::Warning
    ///     | NoticeCategory::DataAdvisory
    ///     | NoticeCategory::SystemMessage => "informational",
    ///     NoticeCategory::RequestError | NoticeCategory::OrderRejection | NoticeCategory::Error => "error",
    ///     _ => "unknown",
    /// };
    /// # let _ = kind;
    /// ```
    pub fn category(&self) -> NoticeCategory {
        classify(self.code, &self.message)
    }

    /// Classify the data-farm connectivity sub-state of this notice.
    ///
    /// Returns `Some(..)` for the data-farm status codes inside
    /// [`WARNING_CODE_RANGE`]; `None` for every other notice. Additive to
    /// [`Notice::category`], which still classifies the farm codes as
    /// [`NoticeCategory::Warning`]. Thin wrapper over
    /// [`ConnectivityStatus::from_code`].
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use ibapi::{Notice, ConnectivityStatus};
    /// # let notice: Notice = unimplemented!();
    /// if notice.connectivity_status() == Some(ConnectivityStatus::Broken) {
    ///     eprintln!("data farm down: {notice}");
    /// }
    /// ```
    pub fn connectivity_status(&self) -> Option<ConnectivityStatus> {
        ConnectivityStatus::from_code(self.code)
    }

    /// Log severity for this notice, derived from [`Notice::category`] so that
    /// every code in a category logs alike regardless of which numeric band it
    /// sits in.
    ///
    /// Informational categories log at `warn` (the caller may want to act:
    /// a fallback engaged, a book must be cleared), with two exceptions at `info`:
    /// the cancellation confirmation, and data-farm notices that need no action.
    /// A farm that is OK, `Inactive` ("…available upon demand") or `Connecting` is
    /// routine on nearly every connect; only `Broken` warns.
    /// System connectivity codes are graded by how much they matter: 1102
    /// (restored, data maintained) → info; 1101 (restored, data lost —
    /// resubscribe required) → warn; 1100 (connectivity lost) and 1300 (socket
    /// reset) → error. Request errors, order rejections and errors log at `error`.
    fn log_level(&self) -> log::Level {
        use log::Level;
        match self.category() {
            NoticeCategory::Cancellation => Level::Info,
            NoticeCategory::Warning
                if matches!(
                    self.connectivity_status(),
                    Some(ConnectivityStatus::Ok | ConnectivityStatus::Inactive | ConnectivityStatus::Connecting)
                ) =>
            {
                Level::Info
            }
            NoticeCategory::Warning | NoticeCategory::DataAdvisory => Level::Warn,
            NoticeCategory::SystemMessage => match self.code {
                CONNECTIVITY_RESTORED_DATA_MAINTAINED_CODE => Level::Info,
                CONNECTIVITY_RESTORED_DATA_LOST_CODE => Level::Warn,
                _ => Level::Error,
            },
            NoticeCategory::RequestError | NoticeCategory::OrderRejection | NoticeCategory::Error => Level::Error,
        }
    }

    /// Log this notice at [`Notice::log_level`].
    pub(crate) fn log(&self) {
        log::log!(self.log_level(), "{self}");
    }
}

impl Display for Notice {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "[{}] {}", self.code, self.message)
    }
}

impl From<crate::transport::routing::DecodedError> for Notice {
    /// Build a Notice from a dispatcher-decoded error payload, moving the
    /// `error_message` and `advanced_order_reject_json` strings and converting
    /// `error_time` (millis-since-epoch) to `OffsetDateTime`.
    fn from(payload: crate::transport::routing::DecodedError) -> Notice {
        let error_time = payload
            .error_time
            .and_then(|millis| OffsetDateTime::from_unix_timestamp_nanos(millis as i128 * 1_000_000).ok());
        Notice {
            request_id: (payload.request_id != crate::transport::routing::UNSPECIFIED_REQUEST_ID).then_some(payload.request_id),
            code: payload.error_code,
            message: payload.error_message,
            error_time,
            advanced_order_reject_json: payload.advanced_order_reject_json,
        }
    }
}