futu_server/

protect.rs

// 限频保护 + 防重放攻击

use std::collections::{HashMap, VecDeque};
use std::time::{Duration, Instant};

use parking_lot::Mutex;
use prost::Message;

use crate::conn::IncomingRequest;
use futu_core::proto_id::*;

/// 限频窗口大小（30 秒）
const FREQ_WINDOW: Duration = Duration::from_secs(30);
const CPP_ACC_DEFAULT_BUCKET: u64 = 0;

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum FreqScope {
    /// Ref: FutuOpenD/Src/APIServer/APIServerCS_Core.cpp:114-129 and
    /// APIServerCS_Protect.hpp:173-180,228-243.
    ///
    /// The central API server gate calls `Protect_IsPassFreqLimitCheck` with
    /// `ACCID_DEFAULT`; QOT/Other paths also use that default account bucket.
    /// Trade protocol account-specific throttling happens in the trading path,
    /// not in this central gate.
    CppDefaultAccount,
}

impl FreqScope {
    fn bucket_scope_id(self, _conn_id: u64) -> u64 {
        match self {
            Self::CppDefaultAccount => CPP_ACC_DEFAULT_BUCKET,
        }
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum PageCursorKind {
    None,
    BytesNextReqKey,
    StringNextKey,
    StringPage,
    Offset,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
struct ProtoFreqRule {
    proto_id: u32,
    limit: u32,
    scope: FreqScope,
    page_cursor: PageCursorKind,
}

impl ProtoFreqRule {
    const fn cpp_default(proto_id: u32, limit: u32, page_cursor: PageCursorKind) -> Self {
        Self {
            proto_id,
            limit,
            scope: FreqScope::CppDefaultAccount,
            page_cursor,
        }
    }

    const fn non_pageable(proto_id: u32, limit: u32) -> Self {
        Self::cpp_default(proto_id, limit, PageCursorKind::None)
    }

    fn is_pageable(self) -> bool {
        self.page_cursor != PageCursorKind::None
    }
}

/// Ref: FutuOpenD/Src/APIServer/APIServerCS_Protect.hpp:30-161.
///
/// C++ uses a 30s sliding window and marks pageable APIs so only first-page
/// requests consume quota. Keep this as a declarative table so new upstream
/// proto ids must make scope/page cursor decisions explicitly.
const PROTO_FREQ_RULES: &[ProtoFreqRule] = &[
    ProtoFreqRule::non_pageable(GET_USER_INFO, 10),
    ProtoFreqRule::non_pageable(VERIFICATION, 10),
    ProtoFreqRule::non_pageable(TRD_UNLOCK_TRADE, 10),
    // Ref: C++ APIServerCS_Core.cpp central gate deliberately skips
    // cache-readable trade APIs plus Qot_GetReference. Cache hits are not
    // counted there; server-forwarding trade paths are throttled inside the
    // trading protocol with the real account id instead of this central gate.
    ProtoFreqRule::non_pageable(TRD_GET_MARGIN_RATIO, 10),
    ProtoFreqRule::non_pageable(TRD_GET_COMBO_MAX_TRD_QTYS, 40),
    ProtoFreqRule::non_pageable(QOT_GET_SECURITY_SNAPSHOT, 60),
    ProtoFreqRule::non_pageable(QOT_GET_PLATE_SET, 10),
    ProtoFreqRule::non_pageable(QOT_GET_PLATE_SECURITY, 10),
    ProtoFreqRule::non_pageable(QOT_GET_OWNER_PLATE, 10),
    ProtoFreqRule::non_pageable(QOT_GET_HOLDING_CHANGE_LIST, 10),
    ProtoFreqRule::non_pageable(QOT_GET_OPTION_CHAIN, 10),
    ProtoFreqRule::non_pageable(QOT_GET_OPTION_QUOTE, 60),
    ProtoFreqRule::non_pageable(QOT_GET_OPTION_STRATEGY_ANALYSIS, 60),
    ProtoFreqRule::non_pageable(QOT_GET_OPTION_STRATEGY, 60),
    ProtoFreqRule::non_pageable(QOT_GET_OPTION_STRATEGY_SPREAD, 60),
    // Ref: C++ `APIServerCS_Protect.hpp:71-72`: distinct non-pageable
    // default-account buckets, each 10 requests per 30-second window.
    ProtoFreqRule::non_pageable(QOT_GET_SEARCH_QUOTE, 10),
    ProtoFreqRule::non_pageable(QOT_GET_SEARCH_NEWS, 10),
    // Ref: owned C++ `APIServerCS_Protect.hpp:164-165`. 3260 owns a
    // non-pageable default-account 60/30s bucket; 3259 is intentionally absent.
    ProtoFreqRule::non_pageable(QOT_REQUEST_INDICATOR_CALC, 60),
    // Ref: C++ `APIServerCS_Protect.hpp:113-116`: three bytes-pageable
    // 60/30s default-account buckets and one non-pageable bucket.
    ProtoFreqRule::cpp_default(
        QOT_GET_OPTION_MARKET_STATISTIC,
        60,
        PageCursorKind::BytesNextReqKey,
    ),
    ProtoFreqRule::cpp_default(
        QOT_GET_OPTION_UNDERLYING_HIS_STATISTIC,
        60,
        PageCursorKind::BytesNextReqKey,
    ),
    ProtoFreqRule::non_pageable(QOT_GET_OPTION_UNDERLYING_OVERVIEW, 60),
    ProtoFreqRule::cpp_default(
        QOT_GET_OPTION_UNDERLYING_HIS_VOLATILITY,
        60,
        PageCursorKind::BytesNextReqKey,
    ),
    // Ref: C++ APIServerCS_Protect.hpp:117-118. Each ranking owns a distinct
    // 60/30s default-account bucket and only an empty string page is counted.
    ProtoFreqRule::cpp_default(
        QOT_GET_OPTION_UNDERLYING_RANK,
        60,
        PageCursorKind::StringPage,
    ),
    ProtoFreqRule::cpp_default(QOT_GET_OPTION_RANK, 60, PageCursorKind::StringPage),
    ProtoFreqRule::cpp_default(QOT_GET_OPTION_EVENT, 60, PageCursorKind::StringPage),
    ProtoFreqRule::cpp_default(QOT_GET_OPTION_EVENT_ALERT, 60, PageCursorKind::StringPage),
    ProtoFreqRule::non_pageable(QOT_SET_OPTION_EVENT_ALERT, 60),
    // Ref: C++ APIServer_Qot_OptionProductZone.cpp:239-250,425-433,
    // 632-640 and APIServer_Qot_OptionEarnings.cpp:112-123. 3311/3313 count
    // only empty string pages; 3312/3314 count every request.
    ProtoFreqRule::cpp_default(
        QOT_GET_OPTION_ZERO_DTE_SCREENER,
        60,
        PageCursorKind::StringPage,
    ),
    ProtoFreqRule::non_pageable(QOT_GET_OPTION_ZERO_DTE_CONTRACT, 60),
    ProtoFreqRule::cpp_default(
        QOT_GET_OPTION_EARNINGS_SCREENER,
        60,
        PageCursorKind::StringPage,
    ),
    ProtoFreqRule::non_pageable(QOT_GET_OPTION_SELLER_SCREENER, 60),
    ProtoFreqRule::cpp_default(QOT_REQUEST_HISTORY_KL, 60, PageCursorKind::BytesNextReqKey),
    ProtoFreqRule::non_pageable(QOT_GET_WARRANT, 60),
    ProtoFreqRule::non_pageable(QOT_REQUEST_REHAB, 60),
    ProtoFreqRule::non_pageable(QOT_GET_CAPITAL_FLOW, 30),
    ProtoFreqRule::non_pageable(QOT_GET_CAPITAL_DISTRIBUTION, 60),
    ProtoFreqRule::non_pageable(QOT_GET_USER_SECURITY, 10),
    ProtoFreqRule::non_pageable(QOT_MODIFY_USER_SECURITY, 10),
    ProtoFreqRule::non_pageable(QOT_STOCK_FILTER, 10),
    ProtoFreqRule::non_pageable(QOT_STOCK_SCREEN, 10),
    ProtoFreqRule::non_pageable(QOT_OPTION_SCREEN, 10),
    ProtoFreqRule::non_pageable(QOT_WARRANT_SCREEN, 60),
    ProtoFreqRule::non_pageable(QOT_GET_IPO_LIST, 10),
    ProtoFreqRule::non_pageable(QOT_GET_FUTURE_INFO, 30),
    ProtoFreqRule::non_pageable(QOT_REQUEST_TRADE_DATE, 30),
    ProtoFreqRule::non_pageable(QOT_SET_PRICE_REMINDER, 60),
    ProtoFreqRule::non_pageable(QOT_GET_PRICE_REMINDER, 10),
    ProtoFreqRule::non_pageable(QOT_GET_USER_SECURITY_GROUP, 10),
    ProtoFreqRule::non_pageable(QOT_GET_MARKET_STATE, 10),
    ProtoFreqRule::non_pageable(QOT_GET_OPTION_EXPIRATION_DATE, 60),
    ProtoFreqRule::non_pageable(QOT_GET_FINANCIALS_EARNINGS_PRICE_MOVE, 30),
    ProtoFreqRule::non_pageable(QOT_GET_FINANCIALS_EARNINGS_PRICE_HISTORY, 30),
    ProtoFreqRule::non_pageable(QOT_GET_FINANCIALS_STATEMENTS, 30),
    ProtoFreqRule::non_pageable(QOT_GET_FINANCIALS_REVENUE_BREAKDOWN, 30),
    ProtoFreqRule::non_pageable(QOT_GET_RESEARCH_ANALYST_CONSENSUS, 30),
    ProtoFreqRule::non_pageable(QOT_GET_RESEARCH_RATING_SUMMARY, 30),
    ProtoFreqRule::non_pageable(QOT_GET_RESEARCH_MORNINGSTAR_REPORT, 30),
    ProtoFreqRule::non_pageable(QOT_GET_VALUATION_DETAIL, 30),
    ProtoFreqRule::non_pageable(QOT_GET_VALUATION_PLATE_STOCK_LIST, 30),
    ProtoFreqRule::non_pageable(QOT_GET_CORPORATE_ACTIONS_DIVIDENDS, 30),
    ProtoFreqRule::non_pageable(QOT_GET_CORPORATE_ACTIONS_BUYBACKS, 30),
    ProtoFreqRule::non_pageable(QOT_GET_CORPORATE_ACTIONS_STOCK_SPLITS, 30),
    ProtoFreqRule::non_pageable(QOT_GET_SHAREHOLDERS_OVERVIEW, 30),
    ProtoFreqRule::non_pageable(QOT_GET_SHAREHOLDERS_HOLDING_CHANGES, 30),
    ProtoFreqRule::cpp_default(
        QOT_GET_SHAREHOLDERS_HOLDER_DETAIL,
        30,
        PageCursorKind::StringNextKey,
    ),
    ProtoFreqRule::non_pageable(QOT_GET_SHAREHOLDERS_INSTITUTIONAL, 30),
    ProtoFreqRule::cpp_default(
        QOT_GET_INSIDER_HOLDER_LIST,
        30,
        PageCursorKind::StringNextKey,
    ),
    ProtoFreqRule::cpp_default(
        QOT_GET_INSIDER_TRADE_LIST,
        30,
        PageCursorKind::StringNextKey,
    ),
    ProtoFreqRule::non_pageable(QOT_GET_COMPANY_PROFILE, 30),
    ProtoFreqRule::non_pageable(QOT_GET_COMPANY_EXECUTIVES, 30),
    ProtoFreqRule::non_pageable(QOT_GET_COMPANY_EXECUTIVE_BACKGROUND, 30),
    ProtoFreqRule::cpp_default(
        QOT_GET_COMPANY_OPERATIONAL_EFFICIENCY,
        30,
        PageCursorKind::StringNextKey,
    ),
    ProtoFreqRule::non_pageable(QOT_GET_TOP_TEN_BUY_SELL_BROKERS, 30),
    ProtoFreqRule::non_pageable(QOT_GET_DAILY_SHORT_VOLUME, 30),
    ProtoFreqRule::non_pageable(QOT_GET_SHORT_INTEREST, 30),
    ProtoFreqRule::non_pageable(QOT_GET_OPTION_VOLATILITY, 30),
    ProtoFreqRule::non_pageable(QOT_GET_OPTION_EXERCISE_PROBABILITY, 30),
    // C++ latest 3401-3433: 30 秒 60 次，pageable=true 时仅首页计数。
    ProtoFreqRule::non_pageable(QOT_GET_EARNINGS_CALENDAR, 60),
    ProtoFreqRule::non_pageable(QOT_GET_MACRO_INDICATOR_LIST, 60),
    ProtoFreqRule::non_pageable(QOT_GET_MACRO_INDICATOR_HISTORY, 60),
    ProtoFreqRule::non_pageable(QOT_GET_FED_WATCH_TARGET_RATE, 60),
    ProtoFreqRule::non_pageable(QOT_GET_FED_WATCH_DOT_PLOT, 60),
    ProtoFreqRule::non_pageable(QOT_GET_EARNINGS_BEAT_RANK, 60),
    ProtoFreqRule::non_pageable(QOT_GET_DIVIDEND_RANK, 60),
    ProtoFreqRule::non_pageable(QOT_GET_DIVIDEND_CALENDAR, 60),
    ProtoFreqRule::non_pageable(QOT_GET_ECONOMIC_CALENDAR, 60),
    ProtoFreqRule::cpp_default(QOT_GET_US_PRE_MARKET_RANK, 60, PageCursorKind::Offset),
    ProtoFreqRule::cpp_default(QOT_GET_US_AFTER_HOURS_RANK, 60, PageCursorKind::Offset),
    ProtoFreqRule::cpp_default(QOT_GET_US_OVERNIGHT_RANK, 60, PageCursorKind::Offset),
    ProtoFreqRule::cpp_default(QOT_GET_TOP_MOVERS_RANK, 60, PageCursorKind::Offset),
    ProtoFreqRule::cpp_default(QOT_GET_HOT_LIST, 60, PageCursorKind::Offset),
    ProtoFreqRule::cpp_default(QOT_GET_SHORT_SELLING_RANK, 60, PageCursorKind::Offset),
    ProtoFreqRule::cpp_default(QOT_GET_PERIOD_CHANGE_RANK, 60, PageCursorKind::Offset),
    ProtoFreqRule::cpp_default(QOT_GET_HIGH_DIVIDEND_SOE_RANK, 60, PageCursorKind::Offset),
    ProtoFreqRule::cpp_default(QOT_GET_INSTITUTION_LIST, 60, PageCursorKind::StringPage),
    ProtoFreqRule::non_pageable(QOT_GET_INSTITUTION_PROFILE, 60),
    ProtoFreqRule::non_pageable(QOT_GET_INSTITUTION_DISTRIBUTION, 60),
    ProtoFreqRule::cpp_default(
        QOT_GET_INSTITUTION_HOLDING_CHANGE,
        60,
        PageCursorKind::StringPage,
    ),
    ProtoFreqRule::cpp_default(
        QOT_GET_INSTITUTION_HOLDING_LIST,
        60,
        PageCursorKind::StringPage,
    ),
    ProtoFreqRule::cpp_default(QOT_GET_ARK_FUND_HOLDING, 60, PageCursorKind::StringPage),
    ProtoFreqRule::non_pageable(QOT_GET_ARK_STOCK_DYNAMIC, 60),
    ProtoFreqRule::cpp_default(
        QOT_GET_ARK_ACTIVE_TRANSACTION,
        60,
        PageCursorKind::StringPage,
    ),
    ProtoFreqRule::cpp_default(QOT_GET_RATING_CHANGE, 60, PageCursorKind::StringPage),
    ProtoFreqRule::cpp_default(
        QOT_GET_INDUSTRIAL_CHAIN_LIST,
        60,
        PageCursorKind::StringPage,
    ),
    ProtoFreqRule::non_pageable(QOT_GET_INDUSTRIAL_CHAIN_DETAIL, 60),
    ProtoFreqRule::non_pageable(QOT_GET_INDUSTRIAL_CHAIN_BY_PLATE, 60),
    ProtoFreqRule::non_pageable(QOT_GET_INDUSTRIAL_PLATE_INFO, 60),
    ProtoFreqRule::cpp_default(
        QOT_GET_INDUSTRIAL_PLATE_STOCK,
        60,
        PageCursorKind::StringPage,
    ),
    ProtoFreqRule::cpp_default(QOT_GET_HEAT_MAP_DATA, 60, PageCursorKind::StringPage),
    ProtoFreqRule::non_pageable(QOT_GET_RISE_FALL_DISTRIBUTION, 60),
    // Ref: FutuOpenD/Src/APIServer/APIServerCS_Protect.hpp:159-162.
    // SkillWrap unusual APIs each use 30 requests per 30 seconds and are
    // non-pageable. The central C++ gate uses ACCID_DEFAULT, so all client
    // connections intentionally share one bucket per proto id.
    ProtoFreqRule::non_pageable(QOT_GET_TECHNICAL_UNUSUAL, 30),
    ProtoFreqRule::non_pageable(QOT_GET_FINANCIAL_UNUSUAL, 30),
    ProtoFreqRule::non_pageable(QOT_GET_DERIVATIVE_UNUSUAL, 30),
    // Ref: frozen C++ aec0f6cda1
    // Src/APIServer/APIServerCS_Protect.hpp:162-173.
    // Event Contract APIs 3434-3439 use 10 requests / 30s. Only 3437-3439
    // declare pageable=true, so their non-empty nextPage requests do not
    // consume the first-page bucket.
    ProtoFreqRule::non_pageable(QOT_GET_EVENT_CONTRACT_CATEGORY, 10),
    ProtoFreqRule::non_pageable(QOT_FILTER_COMPETITION, 10),
    ProtoFreqRule::non_pageable(QOT_GET_EVENT_CONTRACT_SERIES_LIST, 10),
    ProtoFreqRule::cpp_default(
        QOT_GET_EVENT_CONTRACT_EVENT_LIST,
        10,
        PageCursorKind::StringNextKey,
    ),
    ProtoFreqRule::cpp_default(QOT_GET_EVENT_CONTRACT, 10, PageCursorKind::StringNextKey),
    ProtoFreqRule::cpp_default(
        QOT_GET_EVENT_CONTRACT_MILESTONE_LIST,
        10,
        PageCursorKind::StringNextKey,
    ),
    // Combo 3453/3454 use 15 requests / 30s. ComboList is pageable and
    // treats absent/present-empty nextPage as the first page; ComboRfq
    // counts every request.
    ProtoFreqRule::cpp_default(
        QOT_GET_EVENT_CONTRACT_COMBO_LIST,
        15,
        PageCursorKind::StringNextKey,
    ),
    ProtoFreqRule::non_pageable(QOT_GET_EVENT_CONTRACT_COMBO_RFQ, 15),
];

/// 单连接的重放记录
struct ConnFreqRecord {
    /// 防重放：上次见到的 serial number
    last_serial: u32,
}

impl ConnFreqRecord {
    fn new() -> Self {
        Self { last_serial: 0 }
    }
}

#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
struct FreqBucketKey {
    scope_id: u64,
    proto_id: u32,
}

/// 限频保护器
pub struct ProtectionManager {
    records: Mutex<HashMap<u64, ConnFreqRecord>>,
    freq_buckets: Mutex<HashMap<FreqBucketKey, VecDeque<Instant>>>,
    proto_limits: HashMap<u32, ProtoFreqRule>,
}

impl ProtectionManager {
    /// 创建新的 [`ProtectionManager`] 实例。内部自动加载 per-proto_id 默认限
    /// 频表（对齐 C++ 默认配置），不需额外初始化。
    pub fn new() -> Self {
        Self {
            records: Mutex::new(HashMap::new()),
            freq_buckets: Mutex::new(HashMap::new()),
            proto_limits: PROTO_FREQ_RULES
                .iter()
                .map(|rule| (rule.proto_id, *rule))
                .collect(),
        }
    }

    /// 检查请求是否超频
    ///
    /// 返回 true 表示被限频（应拒绝），false 表示通过
    pub fn check_freq_limit(&self, conn_id: u64, proto_id: u32) -> bool {
        self.check_freq_limit_page(conn_id, proto_id, true)
    }

    /// 检查完整请求是否超频。
    ///
    /// 对 pageable API，需要解码请求体判断是否首页；解码失败时按首页处理，
    /// 与 C++ 入口“无法确认续页就走普通频控”的保守行为一致。
    pub fn check_request_freq_limit(&self, conn_id: u64, request: &IncomingRequest) -> bool {
        let mapped_proto = map_proto_to_freq_limit_group(request.proto_id);
        let is_first_page = self
            .proto_limits
            .get(&mapped_proto)
            .filter(|rule| rule.is_pageable())
            .and_then(|_| request_is_first_page_for_limit(mapped_proto, request.body.as_ref()))
            .unwrap_or(true);
        self.check_freq_limit_page(conn_id, request.proto_id, is_first_page)
    }

    /// 检查请求是否超频，并带分页首页标记。
    ///
    /// C++ 对 pageable API 的规则是：第 1 页计入 30 秒滑动窗口，后续页不计数。
    /// 非 pageable API 忽略 `is_first_page`，每次请求都计数。
    pub fn check_freq_limit_page(&self, conn_id: u64, proto_id: u32, is_first_page: bool) -> bool {
        let mapped_proto = map_proto_to_freq_limit_group(proto_id);
        let item = match self.proto_limits.get(&mapped_proto) {
            Some(item) => *item,
            None => return false, // 无限制的协议
        };

        if item.is_pageable() && !is_first_page {
            return false;
        }

        let mut buckets = self.freq_buckets.lock();
        let times = buckets
            .entry(freq_bucket_key(conn_id, mapped_proto, item.scope))
            .or_default();
        let now = Instant::now();

        // 清理过期记录
        while times
            .front()
            .is_some_and(|t| now.duration_since(*t) > FREQ_WINDOW)
        {
            times.pop_front();
        }

        if times.len() as u32 >= item.limit {
            true // 超频
        } else {
            times.push_back(now);
            false
        }
    }

    /// 检查防重放（serial number 必须递增）
    ///
    /// 返回 true 表示可能是重放攻击，false 表示正常
    pub fn check_replay(&self, conn_id: u64, serial_no: u32) -> bool {
        let mut records = self.records.lock();
        let record = records.entry(conn_id).or_insert_with(ConnFreqRecord::new);

        if serial_no <= record.last_serial {
            true // 重放
        } else {
            record.last_serial = serial_no;
            false
        }
    }

    /// 连接断开时清理
    pub fn on_disconnect(&self, conn_id: u64) {
        self.records.lock().remove(&conn_id);
        self.freq_buckets
            .lock()
            .retain(|key, _| key.scope_id != conn_id);
    }
}

fn map_proto_to_freq_limit_group(proto_id: u32) -> u32 {
    if proto_id == futu_core::proto_id::TRD_PLACE_COMBO_ORDER {
        futu_core::proto_id::TRD_PLACE_ORDER
    } else {
        proto_id
    }
}

fn freq_bucket_key(conn_id: u64, proto_id: u32, scope: FreqScope) -> FreqBucketKey {
    FreqBucketKey {
        scope_id: scope.bucket_scope_id(conn_id),
        proto_id,
    }
}

fn request_is_first_page_for_limit(proto_id: u32, body: &[u8]) -> Option<bool> {
    match proto_id {
        QOT_REQUEST_HISTORY_KL => {
            decode_request::<futu_proto::qot_request_history_kl::Request, _>(body, |req| {
                bytes_cursor_is_empty(&req.c2s.next_req_key)
            })
        }
        QOT_GET_OPTION_MARKET_STATISTIC => {
            decode_request::<futu_proto::qot_get_option_market_statistic::Request, _>(body, |req| {
                bytes_cursor_is_empty(&req.c2s.next_page_key)
            })
        }
        QOT_GET_OPTION_UNDERLYING_HIS_STATISTIC => {
            decode_request::<futu_proto::qot_get_option_underlying_his_statistic::Request, _>(
                body,
                |req| bytes_cursor_is_empty(&req.c2s.next_page_key),
            )
        }
        QOT_GET_OPTION_UNDERLYING_HIS_VOLATILITY => {
            decode_request::<futu_proto::qot_get_option_underlying_his_volatility::Request, _>(
                body,
                |req| bytes_cursor_is_empty(&req.c2s.next_page_key),
            )
        }
        QOT_GET_OPTION_UNDERLYING_RANK => {
            decode_request::<futu_proto::qot_get_option_underlying_rank::Request, _>(body, |req| {
                string_offset_is_first_page(&req.c2s.page)
            })
        }
        QOT_GET_OPTION_RANK => {
            decode_request::<futu_proto::qot_get_option_rank::Request, _>(body, |req| {
                string_offset_is_first_page(&req.c2s.page)
            })
        }
        QOT_GET_OPTION_EVENT => {
            decode_request::<futu_proto::qot_get_option_event::Request, _>(body, |req| {
                string_cursor_is_empty(&req.c2s.page)
            })
        }
        QOT_GET_OPTION_EVENT_ALERT => decode_request::<
            futu_proto::qot_get_option_event_alert::Request,
            _,
        >(body, |req| string_cursor_is_empty(&req.c2s.page)),
        QOT_GET_OPTION_ZERO_DTE_SCREENER => {
            decode_request::<futu_proto::qot_get_option_zero_dte_screener::Request, _>(
                body,
                |req| string_cursor_is_empty(&req.c2s.page),
            )
        }
        QOT_GET_OPTION_EARNINGS_SCREENER => {
            decode_request::<futu_proto::qot_get_option_earnings_screener::Request, _>(
                body,
                |req| string_cursor_is_empty(&req.c2s.page),
            )
        }
        QOT_GET_SHAREHOLDERS_HOLDER_DETAIL => {
            decode_request::<futu_proto::qot_get_shareholders_holder_detail::Request, _>(
                body,
                |req| string_cursor_is_empty(&req.c2s.next_key),
            )
        }
        QOT_GET_INSIDER_HOLDER_LIST => {
            decode_request::<futu_proto::qot_get_insider_holder_list::Request, _>(body, |req| {
                string_cursor_is_empty(&req.c2s.next_key)
            })
        }
        QOT_GET_INSIDER_TRADE_LIST => {
            decode_request::<futu_proto::qot_get_insider_trade_list::Request, _>(body, |req| {
                string_cursor_is_empty(&req.c2s.next_key)
            })
        }
        QOT_GET_COMPANY_OPERATIONAL_EFFICIENCY => {
            decode_request::<futu_proto::qot_get_company_operational_efficiency::Request, _>(
                body,
                |req| string_cursor_is_empty(&req.c2s.next_key),
            )
        }
        QOT_GET_US_PRE_MARKET_RANK => decode_request::<
            futu_proto::qot_get_us_pre_market_rank::Request,
            _,
        >(body, |req| offset_is_first_page(req.c2s.offset)),
        QOT_GET_US_AFTER_HOURS_RANK => decode_request::<
            futu_proto::qot_get_us_after_hours_rank::Request,
            _,
        >(body, |req| offset_is_first_page(req.c2s.offset)),
        QOT_GET_US_OVERNIGHT_RANK => decode_request::<
            futu_proto::qot_get_us_overnight_rank::Request,
            _,
        >(body, |req| offset_is_first_page(req.c2s.offset)),
        QOT_GET_TOP_MOVERS_RANK => {
            decode_request::<futu_proto::qot_get_top_movers_rank::Request, _>(body, |req| {
                offset_is_first_page(req.c2s.offset)
            })
        }
        QOT_GET_HOT_LIST => {
            decode_request::<futu_proto::qot_get_hot_list::Request, _>(body, |req| {
                offset_is_first_page(req.c2s.offset)
            })
        }
        QOT_GET_SHORT_SELLING_RANK => decode_request::<
            futu_proto::qot_get_short_selling_rank::Request,
            _,
        >(body, |req| offset_is_first_page(req.c2s.offset)),
        QOT_GET_PERIOD_CHANGE_RANK => decode_request::<
            futu_proto::qot_get_period_change_rank::Request,
            _,
        >(body, |req| offset_is_first_page(req.c2s.offset)),
        QOT_GET_HIGH_DIVIDEND_SOE_RANK => {
            decode_request::<futu_proto::qot_get_high_dividend_soe_rank::Request, _>(body, |req| {
                offset_is_first_page(req.c2s.offset)
            })
        }
        QOT_GET_INSTITUTION_LIST => decode_request::<
            futu_proto::qot_get_institution_list::Request,
            _,
        >(body, |req| string_cursor_is_empty(&req.c2s.page)),
        QOT_GET_INSTITUTION_HOLDING_CHANGE => {
            decode_request::<futu_proto::qot_get_institution_holding_change::Request, _>(
                body,
                |req| string_cursor_is_empty(&req.c2s.page),
            )
        }
        QOT_GET_INSTITUTION_HOLDING_LIST => {
            decode_request::<futu_proto::qot_get_institution_holding_list::Request, _>(
                body,
                |req| string_cursor_is_empty(&req.c2s.page),
            )
        }
        QOT_GET_ARK_FUND_HOLDING => decode_request::<
            futu_proto::qot_get_ark_fund_holding::Request,
            _,
        >(body, |req| string_cursor_is_empty(&req.c2s.page)),
        QOT_GET_ARK_ACTIVE_TRANSACTION => {
            decode_request::<futu_proto::qot_get_ark_active_transaction::Request, _>(body, |req| {
                string_cursor_is_empty(&req.c2s.page)
            })
        }
        QOT_GET_RATING_CHANGE => {
            decode_request::<futu_proto::qot_get_rating_change::Request, _>(body, |req| {
                string_cursor_is_empty(&req.c2s.page)
            })
        }
        QOT_GET_INDUSTRIAL_CHAIN_LIST => {
            decode_request::<futu_proto::qot_get_industrial_chain_list::Request, _>(body, |req| {
                string_cursor_is_empty(&req.c2s.page)
            })
        }
        QOT_GET_INDUSTRIAL_PLATE_STOCK => {
            decode_request::<futu_proto::qot_get_industrial_plate_stock::Request, _>(body, |req| {
                string_cursor_is_empty(&req.c2s.page)
            })
        }
        QOT_GET_HEAT_MAP_DATA => {
            decode_request::<futu_proto::qot_get_heat_map_data::Request, _>(body, |req| {
                string_cursor_is_empty(&req.c2s.page)
            })
        }
        QOT_GET_EVENT_CONTRACT_EVENT_LIST => {
            decode_request::<futu_proto::qot_get_event_contract_event_list::Request, _>(
                body,
                |req| string_cursor_is_empty(&req.c2s.next_page),
            )
        }
        QOT_GET_EVENT_CONTRACT => {
            decode_request::<futu_proto::qot_get_event_contract::Request, _>(body, |req| {
                string_cursor_is_empty(&req.c2s.next_page)
            })
        }
        QOT_GET_EVENT_CONTRACT_MILESTONE_LIST => {
            decode_request::<futu_proto::qot_get_event_contract_milestone_list::Request, _>(
                body,
                |req| string_cursor_is_empty(&req.c2s.next_page),
            )
        }
        QOT_GET_EVENT_CONTRACT_COMBO_LIST => {
            decode_request::<futu_proto::qot_get_event_contract_combo_list::Request, _>(
                body,
                |req| string_cursor_is_empty(&req.c2s.next_page),
            )
        }
        _ => None,
    }
}

#[cfg(test)]
fn has_first_page_decoder(proto_id: u32) -> bool {
    matches!(
        proto_id,
        QOT_REQUEST_HISTORY_KL
            | QOT_GET_OPTION_MARKET_STATISTIC
            | QOT_GET_OPTION_UNDERLYING_HIS_STATISTIC
            | QOT_GET_OPTION_UNDERLYING_HIS_VOLATILITY
            | QOT_GET_OPTION_UNDERLYING_RANK
            | QOT_GET_OPTION_RANK
            | QOT_GET_OPTION_EVENT
            | QOT_GET_OPTION_EVENT_ALERT
            | QOT_GET_OPTION_ZERO_DTE_SCREENER
            | QOT_GET_OPTION_EARNINGS_SCREENER
            | QOT_GET_SHAREHOLDERS_HOLDER_DETAIL
            | QOT_GET_INSIDER_HOLDER_LIST
            | QOT_GET_INSIDER_TRADE_LIST
            | QOT_GET_COMPANY_OPERATIONAL_EFFICIENCY
            | QOT_GET_US_PRE_MARKET_RANK
            | QOT_GET_US_AFTER_HOURS_RANK
            | QOT_GET_US_OVERNIGHT_RANK
            | QOT_GET_TOP_MOVERS_RANK
            | QOT_GET_HOT_LIST
            | QOT_GET_SHORT_SELLING_RANK
            | QOT_GET_PERIOD_CHANGE_RANK
            | QOT_GET_HIGH_DIVIDEND_SOE_RANK
            | QOT_GET_INSTITUTION_LIST
            | QOT_GET_INSTITUTION_HOLDING_CHANGE
            | QOT_GET_INSTITUTION_HOLDING_LIST
            | QOT_GET_ARK_FUND_HOLDING
            | QOT_GET_ARK_ACTIVE_TRANSACTION
            | QOT_GET_RATING_CHANGE
            | QOT_GET_INDUSTRIAL_CHAIN_LIST
            | QOT_GET_INDUSTRIAL_PLATE_STOCK
            | QOT_GET_HEAT_MAP_DATA
            | QOT_GET_EVENT_CONTRACT_EVENT_LIST
            | QOT_GET_EVENT_CONTRACT
            | QOT_GET_EVENT_CONTRACT_MILESTONE_LIST
            | QOT_GET_EVENT_CONTRACT_COMBO_LIST
    )
}

fn decode_request<M, F>(body: &[u8], is_first_page: F) -> Option<bool>
where
    M: Message + Default,
    F: FnOnce(M) -> bool,
{
    M::decode(body).ok().map(is_first_page)
}

fn bytes_cursor_is_empty(cursor: &Option<Vec<u8>>) -> bool {
    cursor.as_ref().is_none_or(Vec::is_empty)
}

fn string_cursor_is_empty(cursor: &Option<String>) -> bool {
    cursor.as_deref().unwrap_or("").is_empty()
}

fn string_offset_is_first_page(cursor: &Option<String>) -> bool {
    let Some(cursor) = cursor.as_deref().filter(|value| !value.is_empty()) else {
        return true;
    };
    // Ref: APIServer_Qot_OptionRank.cpp:206-219,444-457. C++ parses the
    // decimal string into nFrom before deciding whether the request consumes
    // the first-page bucket. Invalid/negative values are rejected by the
    // handler before its rate check and therefore do not consume the bucket.
    cursor.parse::<i32>().is_ok_and(|offset| offset == 0)
}

fn offset_is_first_page(offset: Option<i32>) -> bool {
    // Ref: C++ APIServer_Qot_*Rank.cpp: `!c2s.has_offset() || c2s.offset() == 0`.
    offset.unwrap_or(0) == 0
}

impl Default for ProtectionManager {
    fn default() -> Self {
        Self::new()
    }
}

#[cfg(test)]
mod tests;