futu_mcp/handlers/

proto_json.rs

//! Official proto-JSON passthrough handlers for v10.7 combo-option endpoints.

use std::collections::hash_map::DefaultHasher;
use std::hash::{Hash, Hasher};
use std::sync::Arc;
use std::sync::atomic::{AtomicU32, Ordering};

use anyhow::{Result, anyhow, bail};
use futu_core::trade_market;
use futu_net::client::FutuClient;
use prost::Message;
use serde::Serialize;
use serde::de::DeserializeOwned;

use crate::tool_enums::{ToolEnum, TrdMarketEnum};

static PACKET_SERIAL: AtomicU32 = AtomicU32::new(1);

#[derive(Debug, Clone)]
pub struct ComboTradeContext {
    pub env: &'static str,
    pub acc_id: u64,
    pub market: String,
    pub order_value: Option<f64>,
}

pub fn parse_c2s_json<T>(label: &str, json: &str) -> Result<T>
where
    T: DeserializeOwned,
{
    let mut value: serde_json::Value =
        serde_json::from_str(json).map_err(|err| anyhow!("{label} c2s_json: {err}"))?;
    validate_proto_json_contract(label, &mut value)?;
    serde_json::from_value(value).map_err(|err| anyhow!("{label} c2s_json: {err}"))
}

fn validate_proto_json_contract(label: &str, value: &mut serde_json::Value) -> Result<()> {
    let Some(spec) = futu_surface_spec::lookup_endpoint_by_cli_subcommand(label) else {
        return Ok(());
    };
    futu_surface_spec::validate_and_normalize(spec, value)
        .map_err(|err| anyhow!("{label} c2s_json: {err}"))
}

pub fn parse_combo_max_c2s_json(json: &str) -> Result<futu_proto::trd_get_combo_max_trd_qtys::C2s> {
    parse_combo_c2s_json("combo-max-trd-qtys", json)
}

pub fn parse_place_combo_c2s_json(json: &str) -> Result<futu_proto::trd_place_combo_order::C2s> {
    parse_combo_c2s_json("combo-order", json)
}

fn parse_combo_c2s_json<T>(label: &str, json: &str) -> Result<T>
where
    T: DeserializeOwned,
{
    parse_c2s_json_with_required_paths(
        label,
        json,
        &[
            (["header", "trd_env"].as_slice(), "header.trd_env"),
            (["header", "acc_id"].as_slice(), "header.acc_id"),
            (["header", "trd_market"].as_slice(), "header.trd_market"),
            (["combo_legs"].as_slice(), "combo_legs"),
            (["qty"].as_slice(), "qty"),
            (["order_type"].as_slice(), "order_type"),
        ],
        Some(validate_combo_trade_contract),
    )
}

fn parse_c2s_json_with_required_paths<T>(
    label: &str,
    json: &str,
    required_paths: &[(&[&str], &'static str)],
    extra_validator: Option<fn(&str, &serde_json::Value) -> Result<()>>,
) -> Result<T>
where
    T: DeserializeOwned,
{
    let value: serde_json::Value =
        serde_json::from_str(json).map_err(|err| anyhow!("{label} c2s_json: {err}"))?;
    for (path, name) in required_paths {
        if json_path(&value, path).is_none() {
            bail!("{label} c2s_json missing required field {name}");
        }
    }
    if let Some(validate) = extra_validator {
        validate(label, &value)?;
    }
    serde_json::from_value(value).map_err(|err| anyhow!("{label} c2s_json: {err}"))
}

fn json_path<'a>(value: &'a serde_json::Value, path: &[&str]) -> Option<&'a serde_json::Value> {
    let mut current = value;
    for segment in path {
        current = current.get(*segment)?;
    }
    Some(current)
}

fn validate_combo_trade_contract(label: &str, value: &serde_json::Value) -> Result<()> {
    match json_path(value, &["header", "acc_id"]).and_then(serde_json::Value::as_u64) {
        Some(acc_id) if acc_id > 0 => {}
        _ => bail!("{label} c2s_json header.acc_id must be a positive integer"),
    }

    let legs = json_path(value, &["combo_legs"])
        .and_then(serde_json::Value::as_array)
        .ok_or_else(|| anyhow!("{label} c2s_json combo_legs must be an array"))?;
    if legs.len() < 2 {
        bail!("{label} c2s_json combo_legs must contain at least two legs");
    }

    match json_path(value, &["qty"]).and_then(serde_json::Value::as_f64) {
        Some(qty) if qty > 0.0 => {}
        _ => bail!("{label} c2s_json qty must be positive"),
    }

    let order_type = json_path(value, &["order_type"])
        .and_then(serde_json::Value::as_i64)
        .ok_or_else(|| anyhow!("{label} c2s_json order_type must be an integer"))?;
    if i32::try_from(order_type).is_err() {
        bail!("{label} c2s_json order_type={order_type} is out of range");
    }

    Ok(())
}

pub fn combo_max_context(c2s: &futu_proto::trd_get_combo_max_trd_qtys::C2s) -> Result<u64> {
    if c2s.header.acc_id == 0 {
        bail!("combo-max-trd-qtys header.acc_id is required");
    }
    trd_env_label(c2s.header.trd_env)?;
    trd_write_market_label("combo-max-trd-qtys", c2s.header.trd_market)?;
    Ok(c2s.header.acc_id)
}

pub fn place_combo_context(
    c2s: &futu_proto::trd_place_combo_order::C2s,
) -> Result<ComboTradeContext> {
    if c2s.header.acc_id == 0 {
        bail!("combo-order header.acc_id is required");
    }
    Ok(ComboTradeContext {
        env: trd_env_label(c2s.header.trd_env)?,
        acc_id: c2s.header.acc_id,
        market: trd_write_market_label("combo-order", c2s.header.trd_market)?,
        order_value: c2s.price.map(|price| price * c2s.qty),
    })
}

pub async fn option_quote(
    client: &Arc<FutuClient>,
    c2s: futu_proto::qot_get_option_quote::C2s,
) -> Result<String> {
    let response: futu_proto::qot_get_option_quote::Response = send_proto(
        client,
        futu_core::proto_id::QOT_GET_OPTION_QUOTE,
        futu_proto::qot_get_option_quote::Request { c2s },
    )
    .await?;
    finish_response(
        "option-quote",
        response.ret_type,
        response.ret_msg.as_deref(),
        response.err_code,
        &response,
    )
}

pub async fn option_strategy(
    client: &Arc<FutuClient>,
    c2s: futu_proto::qot_get_option_strategy::C2s,
) -> Result<String> {
    let response: futu_proto::qot_get_option_strategy::Response = send_proto(
        client,
        futu_core::proto_id::QOT_GET_OPTION_STRATEGY,
        futu_proto::qot_get_option_strategy::Request { c2s },
    )
    .await?;
    finish_response(
        "option-strategy",
        response.ret_type,
        response.ret_msg.as_deref(),
        response.err_code,
        &response,
    )
}

pub async fn option_strategy_analysis(
    client: &Arc<FutuClient>,
    c2s: futu_proto::qot_get_option_strategy_analysis::C2s,
) -> Result<String> {
    let response: futu_proto::qot_get_option_strategy_analysis::Response = send_proto(
        client,
        futu_core::proto_id::QOT_GET_OPTION_STRATEGY_ANALYSIS,
        futu_proto::qot_get_option_strategy_analysis::Request { c2s },
    )
    .await?;
    finish_response(
        "option-strategy-analysis",
        response.ret_type,
        response.ret_msg.as_deref(),
        response.err_code,
        &response,
    )
}

pub async fn option_strategy_spread(
    client: &Arc<FutuClient>,
    c2s: futu_proto::qot_get_option_strategy_spread::C2s,
) -> Result<String> {
    let response: futu_proto::qot_get_option_strategy_spread::Response = send_proto(
        client,
        futu_core::proto_id::QOT_GET_OPTION_STRATEGY_SPREAD,
        futu_proto::qot_get_option_strategy_spread::Request { c2s },
    )
    .await?;
    finish_response(
        "option-strategy-spread",
        response.ret_type,
        response.ret_msg.as_deref(),
        response.err_code,
        &response,
    )
}

macro_rules! qot_proto_json_handler {
    ($fn_name:ident, $label:literal, $proto_const:ident, $module:ident) => {
        pub async fn $fn_name(
            client: &Arc<FutuClient>,
            c2s: futu_proto::$module::C2s,
        ) -> Result<String> {
            let response: futu_proto::$module::Response = send_proto(
                client,
                futu_core::proto_id::$proto_const,
                futu_proto::$module::Request { c2s },
            )
            .await?;
            finish_response(
                $label,
                response.ret_type,
                response.ret_msg.as_deref(),
                response.err_code,
                &response,
            )
        }
    };
}

qot_proto_json_handler!(
    earnings_calendar,
    "earnings-calendar",
    QOT_GET_EARNINGS_CALENDAR,
    qot_get_earnings_calendar
);
qot_proto_json_handler!(
    macro_indicator_list,
    "macro-indicator-list",
    QOT_GET_MACRO_INDICATOR_LIST,
    qot_get_macro_indicator_list
);
qot_proto_json_handler!(
    indicator_list,
    "indicator-list",
    QOT_GET_INDICATOR_LIST,
    qot_get_indicator_list
);
qot_proto_json_handler!(
    macro_indicator_history,
    "macro-indicator-history",
    QOT_GET_MACRO_INDICATOR_HISTORY,
    qot_get_macro_indicator_history
);
qot_proto_json_handler!(
    fed_watch_target_rate,
    "fed-watch-target-rate",
    QOT_GET_FED_WATCH_TARGET_RATE,
    qot_get_fed_watch_target_rate
);
qot_proto_json_handler!(
    fed_watch_dot_plot,
    "fed-watch-dot-plot",
    QOT_GET_FED_WATCH_DOT_PLOT,
    qot_get_fed_watch_dot_plot
);
qot_proto_json_handler!(
    earnings_beat_rank,
    "earnings-beat-rank",
    QOT_GET_EARNINGS_BEAT_RANK,
    qot_get_earnings_beat_rank
);
qot_proto_json_handler!(
    dividend_rank,
    "dividend-rank",
    QOT_GET_DIVIDEND_RANK,
    qot_get_dividend_rank
);
qot_proto_json_handler!(
    dividend_calendar,
    "dividend-calendar",
    QOT_GET_DIVIDEND_CALENDAR,
    qot_get_dividend_calendar
);
qot_proto_json_handler!(
    economic_calendar,
    "economic-calendar",
    QOT_GET_ECONOMIC_CALENDAR,
    qot_get_economic_calendar
);
qot_proto_json_handler!(
    us_pre_market_rank,
    "us-pre-market-rank",
    QOT_GET_US_PRE_MARKET_RANK,
    qot_get_us_pre_market_rank
);
qot_proto_json_handler!(
    us_after_hours_rank,
    "us-after-hours-rank",
    QOT_GET_US_AFTER_HOURS_RANK,
    qot_get_us_after_hours_rank
);
qot_proto_json_handler!(
    us_overnight_rank,
    "us-overnight-rank",
    QOT_GET_US_OVERNIGHT_RANK,
    qot_get_us_overnight_rank
);
qot_proto_json_handler!(
    top_movers_rank,
    "top-movers-rank",
    QOT_GET_TOP_MOVERS_RANK,
    qot_get_top_movers_rank
);
qot_proto_json_handler!(hot_list, "hot-list", QOT_GET_HOT_LIST, qot_get_hot_list);
qot_proto_json_handler!(
    short_selling_rank,
    "short-selling-rank",
    QOT_GET_SHORT_SELLING_RANK,
    qot_get_short_selling_rank
);
qot_proto_json_handler!(
    period_change_rank,
    "period-change-rank",
    QOT_GET_PERIOD_CHANGE_RANK,
    qot_get_period_change_rank
);
qot_proto_json_handler!(
    high_dividend_soe_rank,
    "high-dividend-soe-rank",
    QOT_GET_HIGH_DIVIDEND_SOE_RANK,
    qot_get_high_dividend_soe_rank
);
qot_proto_json_handler!(
    institution_list,
    "institution-list",
    QOT_GET_INSTITUTION_LIST,
    qot_get_institution_list
);
qot_proto_json_handler!(
    institution_profile,
    "institution-profile",
    QOT_GET_INSTITUTION_PROFILE,
    qot_get_institution_profile
);
qot_proto_json_handler!(
    institution_distribution,
    "institution-distribution",
    QOT_GET_INSTITUTION_DISTRIBUTION,
    qot_get_institution_distribution
);
qot_proto_json_handler!(
    institution_holding_change,
    "institution-holding-change",
    QOT_GET_INSTITUTION_HOLDING_CHANGE,
    qot_get_institution_holding_change
);
qot_proto_json_handler!(
    institution_holding_list,
    "institution-holding-list",
    QOT_GET_INSTITUTION_HOLDING_LIST,
    qot_get_institution_holding_list
);
qot_proto_json_handler!(
    ark_fund_holding,
    "ark-fund-holding",
    QOT_GET_ARK_FUND_HOLDING,
    qot_get_ark_fund_holding
);
qot_proto_json_handler!(
    ark_stock_dynamic,
    "ark-stock-dynamic",
    QOT_GET_ARK_STOCK_DYNAMIC,
    qot_get_ark_stock_dynamic
);
qot_proto_json_handler!(
    ark_active_transaction,
    "ark-active-transaction",
    QOT_GET_ARK_ACTIVE_TRANSACTION,
    qot_get_ark_active_transaction
);
qot_proto_json_handler!(
    rating_change,
    "rating-change",
    QOT_GET_RATING_CHANGE,
    qot_get_rating_change
);
qot_proto_json_handler!(
    search_quote,
    "search-quote",
    QOT_GET_SEARCH_QUOTE,
    qot_get_search_quote
);
qot_proto_json_handler!(
    search_news,
    "search-news",
    QOT_GET_SEARCH_NEWS,
    qot_get_search_news
);
qot_proto_json_handler!(
    option_market_statistic,
    "option-market-statistic",
    QOT_GET_OPTION_MARKET_STATISTIC,
    qot_get_option_market_statistic
);
qot_proto_json_handler!(
    option_underlying_his_statistic,
    "option-underlying-his-statistic",
    QOT_GET_OPTION_UNDERLYING_HIS_STATISTIC,
    qot_get_option_underlying_his_statistic
);
qot_proto_json_handler!(
    option_underlying_overview,
    "option-underlying-overview",
    QOT_GET_OPTION_UNDERLYING_OVERVIEW,
    qot_get_option_underlying_overview
);
qot_proto_json_handler!(
    option_underlying_his_volatility,
    "option-underlying-his-volatility",
    QOT_GET_OPTION_UNDERLYING_HIS_VOLATILITY,
    qot_get_option_underlying_his_volatility
);
qot_proto_json_handler!(
    option_underlying_rank,
    "option-underlying-rank",
    QOT_GET_OPTION_UNDERLYING_RANK,
    qot_get_option_underlying_rank
);
qot_proto_json_handler!(
    option_rank,
    "option-rank",
    QOT_GET_OPTION_RANK,
    qot_get_option_rank
);
qot_proto_json_handler!(
    option_event,
    "option-event",
    QOT_GET_OPTION_EVENT,
    qot_get_option_event
);
qot_proto_json_handler!(
    option_event_alert,
    "option-event-alert",
    QOT_GET_OPTION_EVENT_ALERT,
    qot_get_option_event_alert
);
qot_proto_json_handler!(
    set_option_event_alert,
    "set-option-event-alert",
    QOT_SET_OPTION_EVENT_ALERT,
    qot_set_option_event_alert
);
qot_proto_json_handler!(
    option_zero_dte_screener,
    "option-zero-dte-screener",
    QOT_GET_OPTION_ZERO_DTE_SCREENER,
    qot_get_option_zero_dte_screener
);
qot_proto_json_handler!(
    option_zero_dte_contract,
    "option-zero-dte-contract",
    QOT_GET_OPTION_ZERO_DTE_CONTRACT,
    qot_get_option_zero_dte_contract
);
qot_proto_json_handler!(
    option_earnings_screener,
    "option-earnings-screener",
    QOT_GET_OPTION_EARNINGS_SCREENER,
    qot_get_option_earnings_screener
);
qot_proto_json_handler!(
    option_seller_screener,
    "option-seller-screener",
    QOT_GET_OPTION_SELLER_SCREENER,
    qot_get_option_seller_screener
);
qot_proto_json_handler!(
    industrial_chain_list,
    "industrial-chain-list",
    QOT_GET_INDUSTRIAL_CHAIN_LIST,
    qot_get_industrial_chain_list
);
qot_proto_json_handler!(
    industrial_chain_detail,
    "industrial-chain-detail",
    QOT_GET_INDUSTRIAL_CHAIN_DETAIL,
    qot_get_industrial_chain_detail
);
qot_proto_json_handler!(
    industrial_chain_by_plate,
    "industrial-chain-by-plate",
    QOT_GET_INDUSTRIAL_CHAIN_BY_PLATE,
    qot_get_industrial_chain_by_plate
);
qot_proto_json_handler!(
    industrial_plate_info,
    "industrial-plate-info",
    QOT_GET_INDUSTRIAL_PLATE_INFO,
    qot_get_industrial_plate_info
);
qot_proto_json_handler!(
    industrial_plate_stock,
    "industrial-plate-stock",
    QOT_GET_INDUSTRIAL_PLATE_STOCK,
    qot_get_industrial_plate_stock
);
qot_proto_json_handler!(
    heat_map_data,
    "heat-map-data",
    QOT_GET_HEAT_MAP_DATA,
    qot_get_heat_map_data
);
qot_proto_json_handler!(
    rise_fall_distribution,
    "rise-fall-distribution",
    QOT_GET_RISE_FALL_DISTRIBUTION,
    qot_get_rise_fall_distribution
);

pub async fn combo_max_trd_qtys(
    client: &Arc<FutuClient>,
    c2s: futu_proto::trd_get_combo_max_trd_qtys::C2s,
) -> Result<String> {
    let response: futu_proto::trd_get_combo_max_trd_qtys::Response = send_proto(
        client,
        futu_core::proto_id::TRD_GET_COMBO_MAX_TRD_QTYS,
        futu_proto::trd_get_combo_max_trd_qtys::Request { c2s },
    )
    .await?;
    finish_response(
        "combo-max-trd-qtys",
        response.ret_type,
        response.ret_msg.as_deref(),
        response.err_code,
        &response,
    )
}

pub async fn place_combo_order(
    client: &Arc<FutuClient>,
    mut c2s: futu_proto::trd_place_combo_order::C2s,
    idempotency_key: Option<String>,
) -> Result<String> {
    c2s.packet_id = match idempotency_key.as_deref() {
        Some(key) => packet_id_for_idempotency_key(key),
        None => {
            let conn_id = client
                .conn_id()
                .ok_or_else(|| anyhow!("combo-order missing InitConnect conn_id"))?;
            next_packet_id(conn_id)
        }
    };

    let response: futu_proto::trd_place_combo_order::Response = send_proto(
        client,
        futu_core::proto_id::TRD_PLACE_COMBO_ORDER,
        futu_proto::trd_place_combo_order::Request { c2s },
    )
    .await?;
    finish_response(
        "combo-order",
        response.ret_type,
        response.ret_msg.as_deref(),
        response.err_code,
        &response,
    )
}

async fn send_proto<Req, Resp>(
    client: &Arc<FutuClient>,
    proto_id: u32,
    request: Req,
) -> Result<Resp>
where
    Req: Message,
    Resp: Message + Default,
{
    let frame = client.request(proto_id, request.encode_to_vec()).await?;
    Resp::decode(frame.body.as_ref()).map_err(|err| anyhow!("decode response: {err}"))
}

fn finish_response<T: Serialize>(
    label: &str,
    ret_type: i32,
    ret_msg: Option<&str>,
    err_code: Option<i32>,
    response: &T,
) -> Result<String> {
    if ret_type != 0 {
        bail!("{label} ret_type={ret_type} msg={ret_msg:?} err_code={err_code:?}");
    }
    Ok(serde_json::to_string_pretty(response)?)
}

fn trd_env_label(trd_env: i32) -> Result<&'static str> {
    match trd_env {
        0 => Ok("simulate"),
        1 => Ok("real"),
        other => {
            bail!("unsupported combo-order header.trd_env={other}; expected 0 simulate or 1 real")
        }
    }
}

fn trd_write_market_label(endpoint: &str, trd_market: i32) -> Result<String> {
    if let Some(label) = trade_market::canonical_fund_trd_market_label(trd_market) {
        bail!(
            "{endpoint} header.trd_market={trd_market} ({label}) is view-only; \
             use a write-capable main market for combo trade paths"
        );
    }
    trd_market_label(endpoint, trd_market)
}

fn trd_market_label(endpoint: &str, trd_market: i32) -> Result<String> {
    let market = TrdMarketEnum::from_i32(trd_market)
        .ok_or_else(|| anyhow!("unsupported {endpoint} header.trd_market={trd_market}"))?;
    let int_values = TrdMarketEnum::all_int_values();
    let string_values = TrdMarketEnum::all_string_values();
    let idx = int_values
        .iter()
        .position(|&value| value == market.as_i32())
        .ok_or_else(|| anyhow!("{endpoint} trd_market has no canonical label"))?;
    Ok(string_values[idx].to_string())
}

fn next_packet_id(conn_id: u64) -> futu_proto::common::PacketId {
    let serial_no = PACKET_SERIAL.fetch_add(1, Ordering::Relaxed);
    futu_proto::common::PacketId { conn_id, serial_no }
}

fn packet_id_for_idempotency_key(key: &str) -> futu_proto::common::PacketId {
    let mut hasher = DefaultHasher::new();
    key.hash(&mut hasher);
    futu_proto::common::PacketId {
        conn_id: hasher.finish(),
        serial_no: 0,
    }
}

#[cfg(test)]
mod tests;