futu_auth/limits/

runtime.rs

//! Split from limits.rs: runtime.
//!
//! pub items: RuntimeCounters,LimitGuard.

use super::*;
use chrono::{DateTime, Local, NaiveDate, Utc};
use dashmap::DashMap;

#[derive(Debug, Default)]
pub struct RuntimeCounters {
    pub(super) counters: DashMap<String, DailyCounter>,
    rates: DashMap<String, RateWindow>,
}

/// v1.4.106 codex 0538 F3 (P2): LimitGuard architecture — accepted-quota
/// 模型而非 attempted-quota.
///
/// **问题** (F3 root cause): 旧版 `check_and_commit` / `check_full_skip_rate`
/// 在限额检查通过的瞬间**直接累加 daily counter**, 即便后续 backend 调用失败
/// 退单也不会回滚 — 用户的 daily quota 被 "attempted" 单消耗 = 攻击者发 N 个
/// 高金额无效单可耗尽合法用户 daily quota.
///
/// **修法 Option B (本次实装)**: 引入 `LimitGuard` RAII pattern:
///
/// 1. `RuntimeCounters::check_limits(...)` — 全部检查 (含 rate + per-order
///    cap + daily peek), 但**不写 daily counter** → 返
///    `Result<LimitGuard, LimitOutcome>`.
/// 2. caller 拿 LimitGuard, 调 backend, **成功后**调 `guard.commit_daily()`
///    才把 daily counter 实际写入.
/// 3. 失败 → `drop(guard)` 不写 counter, 配额自然归还.
/// 4. rate window 在 check_limits 已 commit (rate 是请求节流不是 quota
///    退单不该回收 rate budget — 攻击者重试也算 rate 消耗).
///
/// **legacy compat**: `check_and_commit` / `check_full_skip_rate` 内部仍
/// 调用 check_limits 链路, 但 wrapper 立即 commit daily (保留 v1.4.105 行为).
/// 新调用方 (v1.4.106+ trade handler) 应迁移到 `check_limits` + 显式 commit.
#[must_use = "LimitGuard 必须显式 commit_daily() 或 drop(); drop 时 daily counter 不写入 (accepted-quota 语义)"]
#[derive(Debug)]
pub struct LimitGuard<'a> {
    counters: &'a RuntimeCounters,
    key_id: String,
    /// (value, today, currency) — daily commit 需要的; None = 无 order_value /
    /// 无 daily cap / mutation_no_exposure → commit_daily 是 no-op
    ///
    /// v1.4.106 F4 (P3): tuple 加 `currency` (None = legacy 单桶).
    pending_daily: Option<(f64, NaiveDate, Option<String>)>,
    /// daily cap (commit 时再 try_add 一次会再 check 一次 cap, defense-in-depth)
    daily_cap: Option<f64>,
}

impl<'a> LimitGuard<'a> {
    /// 把 pending daily delta 写入 counter (accepted-quota commit).
    ///
    /// 通常 caller 在 backend 调用 **成功** 后调; backend 失败时
    /// `drop(guard)` 不写, daily quota 不消耗.
    ///
    /// **重要**: commit_daily 是 idempotent — 同一 guard 多次调只写一次
    /// (pending 取走后 set None). 多 caller 共享一个 guard 时安全.
    ///
    /// 返回 `Ok(())` if commit 成功 (或 no-op); `Err(LimitOutcome)` if
    /// commit 时 cap 被超 — 不应发生 (peek 已校验过), 但并发场景下两 guard
    /// 同时 commit 可能撞 cap, 此时第二个 commit 拿 ThroughputReject.
    pub fn commit_daily(mut self) -> Result<(), LimitOutcome> {
        let Some((value, today, currency)) = self.pending_daily.take() else {
            return Ok(());
        };
        let counter = self
            .counters
            .counters
            .entry(self.key_id.clone())
            .or_insert_with(|| DailyCounter::new(today));
        match counter.try_add(currency.as_deref(), value, self.daily_cap, today) {
            Ok(_) => Ok(()),
            Err(DailyAddError::OverCap(msg)) => Err(LimitOutcome::ThroughputReject(msg)),
            Err(DailyAddError::Invalid(reason)) => Err(LimitOutcome::ValueReject(format!(
                "order value invalid ({reason:?}): {value}"
            ))),
        }
    }

    /// 是否有 pending daily delta (false = no-op commit, e.g. mutation_no_exposure)
    #[must_use]
    pub fn has_pending_daily(&self) -> bool {
        self.pending_daily.is_some()
    }
}

impl RuntimeCounters {
    pub fn new() -> Self {
        Self::default()
    }

    /// v1.4.106 codex 0538 F3 (P2): accepted-quota architecture entry.
    ///
    /// 跑全部限额检查 (whitelist + per-order cap + rate + daily peek), 但**不**
    /// 累加 daily counter — 返 [`LimitGuard`] 让 caller 在 backend 成功后
    /// 显式 `commit_daily()`.
    ///
    /// 失败 → `drop(guard)` 不写 daily counter, 配额自然归还 (与 legacy
    /// `check_and_commit` 在失败前就累加的 attempted-quota 行为相反).
    ///
    /// **rate** 在本函数仍 commit (rate 是节流不是 quota, 失败重试也算消耗).
    ///
    /// 参数:
    /// - `commit_rate`: true = 跑 rate window 累加 (auth middleware 入口);
    ///   false = 跳过 rate (handler 层重入, 等同 `check_full_skip_rate`).
    pub fn check_limits<'a>(
        &'a self,
        key_id: &str,
        limits: &Limits,
        ctx: &CheckCtx,
        now: DateTime<Utc>,
        commit_rate: bool,
    ) -> Result<LimitGuard<'a>, LimitOutcome> {
        // 0. acc_id 白名单
        if let (Some(allowed), Some(id)) = (&limits.allowed_acc_ids, ctx.acc_id)
            && !allowed.is_empty()
            && !allowed.contains(&id)
        {
            return Err(LimitOutcome::WhitelistReject(format!(
                "acc_id {id} not in allowed list {allowed:?}"
            )));
        }

        // 1. 市场白名单
        if let Some(markets) = &limits.allowed_markets
            && !markets.is_empty()
            && !ctx.market.is_empty()
            && !markets.contains(&ctx.market)
        {
            return Err(LimitOutcome::WhitelistReject(format!(
                "market {:?} not in allowed list {:?}",
                ctx.market, markets
            )));
        }

        // 2. 品种白名单
        if let Some(symbols) = &limits.allowed_symbols
            && !symbols.is_empty()
            && !ctx.symbol.is_empty()
            && !symbols.contains(&ctx.symbol)
        {
            return Err(LimitOutcome::WhitelistReject(format!(
                "symbol {:?} not in allowed list",
                ctx.symbol
            )));
        }

        // 3. 交易方向白名单
        if let (Some(allowed), Some(side)) = (&limits.allowed_trd_sides, &ctx.trd_side)
            && !allowed.is_empty()
            && !allowed.contains(side)
        {
            return Err(LimitOutcome::WhitelistReject(format!(
                "trd_side {side:?} not in allowed list {allowed:?}"
            )));
        }

        // 4. 时间窗口
        if let Some(spec) = &limits.hours_window {
            match parse_window(spec) {
                Ok((start, end)) => {
                    let now_local = now.with_timezone(&Local).time();
                    if !in_window(now_local, start, end) {
                        return Err(LimitOutcome::ThroughputReject(format!(
                            "outside hours window {spec} (now={})",
                            now_local.format("%H:%M")
                        )));
                    }
                }
                Err(e) => {
                    return Err(LimitOutcome::ThroughputReject(format!(
                        "invalid hours_window {spec:?}: {e}"
                    )));
                }
            }
        }

        // 5. 单笔上限 + F1 fail-closed validation
        if let Some(value) = ctx.order_value {
            if let Err(reason) = validate_order_value(value) {
                return Err(LimitOutcome::ValueReject(format!(
                    "order value invalid ({reason:?}): {value}"
                )));
            }
            if let Some(cap) = limits.max_order_value
                && value > cap + f64::EPSILON
            {
                return Err(LimitOutcome::ValueReject(format!(
                    "order value {value:.2} exceeds per-order cap {cap:.2}"
                )));
            }
        }

        // 6. per-minute 速率 (commit_rate=true 才真累加)
        if commit_rate && let Some(max) = limits.max_orders_per_minute {
            let window = self.rates.entry(key_id.to_string()).or_default();
            if let Err(e) = window.try_record(now, max) {
                return Err(LimitOutcome::ThroughputReject(e));
            }
        }

        // 7. 日累计 — peek only (不写), commit 由 LimitGuard::commit_daily 触发.
        //    F2: mutation_no_exposure=true → 不算 daily.
        //    F4: per-currency 维度 — ctx.currency 决定写哪个桶.
        let pending_daily = if !ctx.mutation_no_exposure
            && let (Some(value), Some(_)) = (ctx.order_value, limits.max_daily_value)
        {
            let daily_currency = ctx.daily_currency();
            let today = now.date_naive();
            let counter = self
                .counters
                .entry(key_id.to_string())
                .or_insert_with(|| DailyCounter::new(today));
            match counter.peek_add(
                daily_currency.as_deref(),
                value,
                limits.max_daily_value,
                today,
            ) {
                Ok(_) => Some((value, today, daily_currency)),
                Err(DailyAddError::OverCap(msg)) => {
                    return Err(LimitOutcome::ThroughputReject(msg));
                }
                Err(DailyAddError::Invalid(reason)) => {
                    return Err(LimitOutcome::ValueReject(format!(
                        "order value invalid ({reason:?}): {value}"
                    )));
                }
            }
        } else {
            None
        };

        Ok(LimitGuard {
            counters: self,
            key_id: key_id.to_string(),
            pending_daily,
            daily_cap: limits.max_daily_value,
        })
    }

    /// 执行全部限额检查；通过则（若提供 order_value）累加日计数 + 记录速率窗口时间戳
    ///
    /// 检查顺序：市场 → 品种 → 方向 → 时间窗 → 单笔 → 速率 → 日累计。
    /// 前面的便宜检查先跑；日累计放最后是因为它有副作用（累加），
    /// 前面 reject 就不该动计数器。
    ///
    /// **v1.4.106 codex 0538 F3**: 此 wrapper 保持 v1.4.105 attempted-quota
    /// 行为 (legacy compat). 新代码应迁移到 [`Self::check_limits`] +
    /// [`LimitGuard::commit_daily`] 走 accepted-quota 模型.
    #[must_use]
    pub fn check_and_commit(
        &self,
        key_id: &str,
        limits: &Limits,
        ctx: &CheckCtx,
        now: DateTime<Utc>,
    ) -> LimitOutcome {
        // 0. acc_id 白名单（v1.4.35 加）—— 最早检查，因为粒度最细 + 最容易命中
        //    （不同 agent / bot 分配不同 acc_id 范围是主流场景）。
        //    acc_id=None 表示非账户特定请求（subscribe / quote / global-state）跳过。
        //    v1.4.36 Bug #1 修：此类拒绝用 WhitelistReject，映射到 HTTP 403。
        if let (Some(allowed), Some(id)) = (&limits.allowed_acc_ids, ctx.acc_id)
            && !allowed.is_empty()
            && !allowed.contains(&id)
        {
            return LimitOutcome::WhitelistReject(format!(
                "acc_id {id} not in allowed list {allowed:?}"
            ));
        }

        // 1. 市场白名单（同上，v1.4.36 Bug #1：WhitelistReject → 403）
        if let Some(markets) = &limits.allowed_markets
            && !markets.is_empty()
            && !ctx.market.is_empty()
            && !markets.contains(&ctx.market)
        {
            return LimitOutcome::WhitelistReject(format!(
                "market {:?} not in allowed list {:?}",
                ctx.market, markets
            ));
        }

        // 2. 品种白名单（v1.4.36 Bug #1：WhitelistReject → 403）
        if let Some(symbols) = &limits.allowed_symbols
            && !symbols.is_empty()
            && !ctx.symbol.is_empty()
            && !symbols.contains(&ctx.symbol)
        {
            return LimitOutcome::WhitelistReject(format!(
                "symbol {:?} not in allowed list",
                ctx.symbol
            ));
        }

        // 3. 交易方向白名单（v1.4.36 Bug #1：WhitelistReject → 403）
        if let (Some(allowed), Some(side)) = (&limits.allowed_trd_sides, &ctx.trd_side)
            && !allowed.is_empty()
            && !allowed.contains(side)
        {
            return LimitOutcome::WhitelistReject(format!(
                "trd_side {side:?} not in allowed list {allowed:?}"
            ));
        }

        // 4. 时间窗口（rate-like，ThroughputReject → 429 让客户端 backoff 重试）
        if let Some(spec) = &limits.hours_window {
            match parse_window(spec) {
                Ok((start, end)) => {
                    let now_local = now.with_timezone(&Local).time();
                    if !in_window(now_local, start, end) {
                        return LimitOutcome::ThroughputReject(format!(
                            "outside hours window {spec} (now={})",
                            now_local.format("%H:%M")
                        ));
                    }
                }
                Err(e) => {
                    return LimitOutcome::ThroughputReject(format!(
                        "invalid hours_window {spec:?}: {e}"
                    ));
                }
            }
        }

        // 5. 单笔上限（ValueReject → 403，不该 backoff 重试，需要拆单或换 key）
        //
        // v1.4.106 codex 0538 F1 P1 SECURITY: 先过 validate_order_value
        // 拒 NaN / inf / negative，否则 NaN compare 总 false bypass cap，
        // 负数让 daily counter 倒减，inf 让 counter 饱和。
        if let Some(value) = ctx.order_value {
            if let Err(reason) = validate_order_value(value) {
                return LimitOutcome::ValueReject(format!(
                    "order value invalid ({reason:?}): {value}"
                ));
            }
            if let Some(cap) = limits.max_order_value
                && value > cap + f64::EPSILON
            {
                return LimitOutcome::ValueReject(format!(
                    "order value {value:.2} exceeds per-order cap {cap:.2}"
                ));
            }
        }

        // 6. per-minute 速率（ThroughputReject → 429）
        if let Some(max) = limits.max_orders_per_minute {
            let window = self.rates.entry(key_id.to_string()).or_default();
            if let Err(e) = window.try_record(now, max) {
                return LimitOutcome::ThroughputReject(e);
            }
        }

        // 7. 日累计上限（ThroughputReject → 429 / ValueReject → 403 if invalid）
        //
        // v1.4.106 codex 0538 F2 (P2): mutation_no_exposure=true (Cancel /
        // Disable / Enable / Delete 类 mutation) 跳过 daily counter — 它们
        // 不产生新 exposure delta. rate / acc_id / market 上面已查.
        if !ctx.mutation_no_exposure
            && let (Some(value), Some(_)) = (ctx.order_value, limits.max_daily_value)
        {
            let daily_currency = ctx.daily_currency();
            let today = now.date_naive();
            let counter = self
                .counters
                .entry(key_id.to_string())
                .or_insert_with(|| DailyCounter::new(today));
            match counter.try_add(
                daily_currency.as_deref(),
                value,
                limits.max_daily_value,
                today,
            ) {
                Ok(_) => {}
                Err(DailyAddError::OverCap(msg)) => return LimitOutcome::ThroughputReject(msg),
                Err(DailyAddError::Invalid(reason)) => {
                    // F1 defense-in-depth: 上面已校验过，这里不应该到达；
                    // 但如果到达说明并发态下值已变 → fail-closed reject.
                    return LimitOutcome::ValueReject(format!(
                        "order value invalid ({reason:?}): {value}"
                    ));
                }
            }
        }

        LimitOutcome::Allow
    }

    /// handler 层细粒度检查：跑 market / symbol / trd_side / hours / per_order /
    /// daily 全套，**但跳过 rate** —— rate 已经在 auth 中间件层（v1.0）
    /// commit 过了，handler 再 commit 一次会让 rate 窗口计 2 次。
    ///
    /// 典型用法：REST `/api/order` 路由 / gRPC `request(2202)` 这种 handler
    /// 已经知道完整下单参数（market/symbol/value/side），调用方先在 middleware
    /// 跑 rate+hours 全局闸门（`check_and_commit` with empty CheckCtx），过了
    /// 再在 handler 里跑这个方法做细粒度检查。
    ///
    /// **注意**：daily 计数器**会**累加 —— 这是必须的，因为 rate 不能算"额度"，
    /// daily 才是真实金额额度。
    #[must_use]
    pub fn check_full_skip_rate(
        &self,
        key_id: &str,
        limits: &Limits,
        ctx: &CheckCtx,
        now: DateTime<Utc>,
    ) -> LimitOutcome {
        // 0. acc_id 白名单（v1.4.35；v1.4.36 Bug #1 改 WhitelistReject → 403）
        if let (Some(allowed), Some(id)) = (&limits.allowed_acc_ids, ctx.acc_id)
            && !allowed.is_empty()
            && !allowed.contains(&id)
        {
            return LimitOutcome::WhitelistReject(format!(
                "acc_id {id} not in allowed list {allowed:?}"
            ));
        }

        // 1. 市场白名单（v1.4.36 Bug #1：WhitelistReject → 403）
        if let Some(markets) = &limits.allowed_markets
            && !markets.is_empty()
            && !ctx.market.is_empty()
            && !markets.contains(&ctx.market)
        {
            return LimitOutcome::WhitelistReject(format!(
                "market {:?} not in allowed list {:?}",
                ctx.market, markets
            ));
        }

        // 2. 品种白名单（v1.4.36 Bug #1：WhitelistReject → 403）
        if let Some(symbols) = &limits.allowed_symbols
            && !symbols.is_empty()
            && !ctx.symbol.is_empty()
            && !symbols.contains(&ctx.symbol)
        {
            return LimitOutcome::WhitelistReject(format!(
                "symbol {:?} not in allowed list",
                ctx.symbol
            ));
        }

        // 3. 交易方向白名单（v1.4.36 Bug #1：WhitelistReject → 403）
        if let (Some(allowed), Some(side)) = (&limits.allowed_trd_sides, &ctx.trd_side)
            && !allowed.is_empty()
            && !allowed.contains(side)
        {
            return LimitOutcome::WhitelistReject(format!(
                "trd_side {side:?} not in allowed list {allowed:?}"
            ));
        }

        // 4. 时间窗口（ThroughputReject → 429）
        if let Some(spec) = &limits.hours_window {
            match parse_window(spec) {
                Ok((start, end)) => {
                    let now_local = now.with_timezone(&Local).time();
                    if !in_window(now_local, start, end) {
                        return LimitOutcome::ThroughputReject(format!(
                            "outside hours window {spec} (now={})",
                            now_local.format("%H:%M")
                        ));
                    }
                }
                Err(e) => {
                    return LimitOutcome::ThroughputReject(format!(
                        "invalid hours_window {spec:?}: {e}"
                    ));
                }
            }
        }

        // 5. 单笔上限（ValueReject → 403）
        //
        // v1.4.106 codex 0538 F1 P1 SECURITY: validate_order_value 先于 cap.
        if let Some(value) = ctx.order_value {
            if let Err(reason) = validate_order_value(value) {
                return LimitOutcome::ValueReject(format!(
                    "order value invalid ({reason:?}): {value}"
                ));
            }
            if let Some(cap) = limits.max_order_value
                && value > cap + f64::EPSILON
            {
                return LimitOutcome::ValueReject(format!(
                    "order value {value:.2} exceeds per-order cap {cap:.2}"
                ));
            }
        }

        // 6. **跳过 rate**（已在 auth 层 commit）

        // 7. 日累计上限（ThroughputReject → 429 / ValueReject → 403 if invalid）
        //
        // v1.4.106 codex 0538 F2 (P2): mutation_no_exposure=true 跳过 daily
        // counter (Cancel / Disable / Enable / Delete 不动 exposure).
        if !ctx.mutation_no_exposure
            && let (Some(value), Some(_)) = (ctx.order_value, limits.max_daily_value)
        {
            let daily_currency = ctx.daily_currency();
            let today = now.date_naive();
            let counter = self
                .counters
                .entry(key_id.to_string())
                .or_insert_with(|| DailyCounter::new(today));
            match counter.try_add(
                daily_currency.as_deref(),
                value,
                limits.max_daily_value,
                today,
            ) {
                Ok(_) => {}
                Err(DailyAddError::OverCap(msg)) => return LimitOutcome::ThroughputReject(msg),
                Err(DailyAddError::Invalid(reason)) => {
                    return LimitOutcome::ValueReject(format!(
                        "order value invalid ({reason:?}): {value}"
                    ));
                }
            }
        }

        LimitOutcome::Allow
    }

    #[cfg(test)]
    pub(super) fn peek_total(&self, key_id: &str) -> f64 {
        self.counters
            .get(key_id)
            .map(|c| c.peek_total())
            .unwrap_or(0.0)
    }

    #[cfg(test)]
    pub(super) fn peek_total_for_currency(&self, key_id: &str, currency: &str) -> f64 {
        self.counters
            .get(key_id)
            .map(|c| c.peek_total_for_currency(currency))
            .unwrap_or(0.0)
    }
}