futu_opend/

cli.rs

//! v1.4.110 P1-2: CLI 类型抽自 main.rs lines 125-496.
//!
//! Platform / LoginRegion / LogLevel enums + Args (clap derive).

use clap::Parser;

/// 账号平台（v1.4.14+）
///
/// 决定 HTTP 认证服务器域名。两个平台**独立账号体系**：
/// - `futunn`（默认）—— 牛牛，用户为 CN / HK 归属，auth.futunn.com
/// - `moomoo` —— moomoo，用户为 US / SG / AU / JP / CA 归属，auth.moomoo.com
///
/// 同一手机号 / 邮箱可以在两边分别注册独立账号（不同密码）。`--platform`
/// 让用户显式选择，避免"同号两边都有"时我们默认发 futunn 登到错账号。
///
/// `--auth-server <url>` 显式指定 URL 时**覆盖** `--platform`（给测试环境用）。
#[derive(Debug, Clone, Copy, clap::ValueEnum, Default, serde::Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
#[clap(rename_all = "lower")]
pub enum Platform {
    /// 牛牛（Futubull）—— CN / HK 账号
    #[default]
    Futunn,
    /// moomoo —— US / SG / AU / JP / CA 账号
    Moomoo,
}

impl Platform {
    pub fn auth_server(self) -> &'static str {
        match self {
            Self::Futunn => "https://auth.futunn.com",
            Self::Moomoo => "https://auth.moomoo.com",
        }
    }

    pub fn name(self) -> &'static str {
        match self {
            Self::Futunn => "futunn",
            Self::Moomoo => "moomoo",
        }
    }
}

/// v1.4.40 #12 fix (external reviewer exhaustive report): `--login-region` 封闭 enum。
///
/// v1.4.39 及以前接受任意字符串（`gz` / `us` / `moomoo` / `wuhan` / 日期串都被
/// 静默吃掉，无法反馈给用户），且**对 moomoo 账户此 flag 永远不生效**（daemon 内
/// commconfig 按 `user_attribution` 查 `guaranteed_ip` 覆盖）。
///
/// v1.4.40 起：
/// - clap `ValueEnum` 只接受 `gz` / `sh` / `hk` 三个合法值，非法值 fail-fast
/// - 对 `--platform moomoo` 启动时若用户传了 `--login-region`，WARN log 显式说明
///   "此 flag 仅对 futunn 生效，moomoo 账户按 user_attribution 自动路由"
///
/// 三个值对应 futunn 平台的广州 / 上海 / 香港数据中心标识（C++ OpenD 历史约定）。
#[derive(Debug, Clone, Copy, clap::ValueEnum, serde::Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
#[clap(rename_all = "lower")]
pub enum LoginRegion {
    /// futunn 广州数据中心（默认）
    Gz,
    /// futunn 上海数据中心
    Sh,
    /// futunn 香港数据中心
    Hk,
}

impl LoginRegion {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Gz => "gz",
            Self::Sh => "sh",
            Self::Hk => "hk",
        }
    }
}

/// v1.4.73 BUG-015 fix：`--log-level` silent accept 非法值（tracing-subscriber
/// `EnvFilter::new()` 对非法值返"deny-all" filter 吞所有 log，exit=0 像正常跑
/// 但用户看不到任何输出）。
///
/// 用 clap `ValueEnum` 约束有效值集合（对齐 v1.4.40 `LoginRegion` 做法），
/// 非法值被 clap 在 parse 阶段拒绝 → exit=2 + 清晰错误输出。
///
/// 有效值 = `tracing` 标准 `LevelFilter` / `Level`：
/// `trace` / `debug` / `info` / `warn` / `error` / `off`。
#[derive(Debug, Clone, Copy, clap::ValueEnum, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "lowercase")]
#[clap(rename_all = "lower")]
pub enum LogLevel {
    /// 最细粒度（含 tracing span entry/exit）
    Trace,
    /// 调试信息（默认最噪）
    Debug,
    /// 标准运行日志（默认）
    Info,
    /// 警告及以上
    Warn,
    /// 只有错误
    Error,
    /// 关闭所有日志
    Off,
}

impl LogLevel {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Trace => "trace",
            Self::Debug => "debug",
            Self::Info => "info",
            Self::Warn => "warn",
            Self::Error => "error",
            Self::Off => "off",
        }
    }

    /// 从 config 文件的 string 解析（XML / TOML）—— 非 clap 路径使用。
    /// 非法值返 None 让调用方 `eprintln!` + exit。
    ///
    /// codex 0547 F3 (P2) 之后: production 路径已改用 serde Option<LogLevel>
    /// 直接 parse. 此 helper 只在测试里保留旧 alias 行为证据，避免把
    /// "warning" / "silent" / "none" 重新接回 production 配置解析。
    #[cfg(test)]
    pub fn from_str_opt(s: &str) -> Option<Self> {
        match s.trim().to_ascii_lowercase().as_str() {
            "trace" => Some(Self::Trace),
            "debug" => Some(Self::Debug),
            "info" => Some(Self::Info),
            "warn" | "warning" => Some(Self::Warn),
            "error" => Some(Self::Error),
            "off" | "none" | "silent" => Some(Self::Off),
            _ => None,
        }
    }
}

/// FutuOpenD Rust Gateway — 完全替代 C++ OpenD
#[derive(Parser)]
#[command(name = "futu-opend", version, about = "FutuOpenD Rust Gateway")]
pub struct Args {
    /// XML 配置文件路径 (兼容 C++ FutuOpenD.xml)
    #[arg(long)]
    pub cfg_file: Option<String>,

    /// TOML 配置文件路径 (v1.4.2+；字段与 CLI 参数对齐, CLI 参数覆盖).
    ///
    /// codex 0547 F6 (P3): 字段白名单 (与 `XmlConfig` schema 一致):
    ///   - 登录: `login_account` / `login_pwd` / `login_pwd_md5` /
    ///     `login_pwd_file` / `login_region` / `platform`
    ///   - 监听: `ip` / `port` (alias `api_port`) / `rest_port` /
    ///     `grpc_port` / `websocket_port` / `telnet_port` / `telnet_ip`
    ///   - 安全: `rsa_private_key` / `rest_keys_file` / `grpc_keys_file` /
    ///     `ws_keys_file` / `audit_log` / `allow_tcp_unauthenticated`
    ///   - 系统: `lang` / `log_level` / `tz` /
    ///     `client_sig_proactive_refresh` / `client_sig_reactive_refresh` /
    ///     `language_pack_auto_update` / `language_pack_endpoint` /
    ///     `language_pack_cache_dir` / `language_pack_update_timeout_ms`
    ///
    /// **不能写 TOML 的 CLI-only 字段** (运维 / 调试 / 一次性流程):
    ///   `device_id` / `reset_device` / `setup_only` / `verify_code` /
    ///   `json_log` / `inject_auth_failure_every` (dev-flags feature only)
    ///
    /// 任何 unknown field / typo 触发 fatal parse error (BUG-006
    /// `deny_unknown_fields`), daemon abort. 不再 silent drop.
    ///
    /// 示例:
    /// ```toml
    /// login_account = "123456"
    /// ip = "0.0.0.0"
    /// port = 11111
    /// rest_port = 22222
    /// grpc_port = 33333
    /// rest_keys_file = "/etc/futu/keys.json"
    /// audit_log = "/var/log/futu-audit.jsonl"
    /// tz = "Asia/Hong_Kong"
    /// ```
    #[arg(long)]
    pub config: Option<String>,

    /// API 服务监听地址
    #[arg(short = 'i', long)]
    pub ip: Option<String>,

    /// API 服务监听端口
    #[arg(short = 'p', long)]
    pub port: Option<u16>,

    /// 登录账号
    #[arg(long)]
    pub login_account: Option<String>,

    /// 登录密码明文（legacy argv fallback；不建议生产使用：会暴露在 `ps` 输出
    /// 和 shell history。优先用 `futucli set-login-pwd` 或 `--login-pwd-file`）
    #[arg(long)]
    pub login_pwd: Option<String>,

    /// 登录密码 MD5 (32 位小写 hex；legacy argv fallback；不建议生产使用：
    /// MD5 可直接登录，且同样会暴露在 `ps` 输出和 shell history)
    #[arg(long)]
    pub login_pwd_md5: Option<String>,

    /// 登录密码从**文件**读（v1.4.18+）——适用于 systemd `LoadCredential=` /
    /// Docker secrets 场景。argv 里只有文件路径，不会泄露明文。
    ///
    /// 文件内容：明文密码（末尾 `\n` 会被 trim 掉）。
    #[arg(long)]
    pub login_pwd_file: Option<String>,

    /// 后端连接区域 (gz / sh / hk) —— **仅对 `--platform futunn` 生效**
    ///
    /// 这三个值是 **futunn 平台**的广州 / 上海 / 香港数据中心标识。
    ///
    /// **对 `--platform moomoo` 账户此 flag 会被忽略**：daemon 内 commconfig 根据
    /// `user_attribution` 查 `guaranteed_ip` 列表覆盖。想切 moomoo 各区用
    /// `--platform moomoo` + 账号本身决定归属。
    ///
    /// v1.4.40 起 clap 封闭 enum 拒绝非法值（v1.4.39 及以前静默接受任意字符串）。
    #[arg(long, value_enum)]
    pub login_region: Option<LoginRegion>,

    /// 账号平台（v1.4.14+）—— futunn=牛牛/CN/HK，moomoo=US/SG/AU/JP/CA
    ///
    /// 同手机号 / 邮箱可以在两边各注册独立账号（不同密码）。默认 futunn。
    /// `--auth-server` 显式指定 URL 时覆盖 `--platform`。
    #[arg(long, value_enum)]
    pub platform: Option<Platform>,

    /// 认证服务器 URL（覆盖 `--platform` 推导的默认值，主要给测试环境用）
    #[arg(long)]
    pub auth_server: Option<String>,

    /// 设备 ID（16 位 hex）—— 覆盖自动生成/持久化的值。
    ///
    /// v1.4.17+ 默认从 `~/.futu-opend-rs/device-{hash}.dat` 读（首次随机生成
    /// 并写入）。本参数用于显式指定，并**更新**持久化文件。
    ///
    /// 如果 device_id 被服务端锁定（`error_code=15/21`），可用
    /// `--reset-device` 一键清空文件让下次启动随机生成新值。
    #[arg(long)]
    pub device_id: Option<String>,

    /// 重置 device_id + credentials 文件后再启动（v1.4.17+）
    ///
    /// 当用户的 device_id 因空验证码 / 多次 SMS 输错被服务端锁定，
    /// 所有后续请求都返回 `error_code=15 长时间没有登录` 无法恢复。
    /// 本参数删除 `~/.futu-opend-rs/device-{hash}.dat` 和
    /// `credentials-{hash}.json`，下次 login 重新生成随机 device_id 走
    /// 完整首登流程。
    #[arg(long)]
    pub reset_device: bool,

    /// 只完成首次设备验证 + 凭据缓存后退出（v1.4.17+）
    ///
    /// 用于 systemd / Docker / cron 场景：先在**前台终端**手动跑一次
    /// `futu-opend --setup-only` 完成 SMS 验证，写入 credentials 文件，然后
    /// 生产环境启动时直接走 remember-login 跳过 SMS。
    #[arg(long)]
    pub setup_only: bool,

    /// **v1.4.57 外部 UX-04**（加拿大同事 SMS + Telegram 中继场景必需）：
    /// 直接传入 SMS 验证码，跳过 stdin prompt。用于 agent / CI / 远程中继场景
    /// （SMS 验证码通过 Telegram/IM 转发，60 秒失效，直接用 stdin 输入来不及）。
    ///
    /// 典型用法：
    /// ```bash
    /// # 1. 先不带 --verify-code 启动触发 SMS（会 fail + 退出，但 SMS 已发）
    /// futu-opend --setup-only --login-account X --login-pwd Y
    /// # 2. 收到 SMS 后立即带验证码重新启动
    /// futu-opend --setup-only --login-account X --login-pwd Y --verify-code 123456
    /// ```
    #[arg(long)]
    pub verify_code: Option<String>,

    /// 日志级别（v1.4.73 BUG-015: clap ValueEnum 约束有效值 trace/debug/info/warn/error/off，
    /// 非法值 parse 阶段拒绝 + 清晰错误，不再 silent 吞 log）
    #[arg(long, value_enum)]
    pub log_level: Option<LogLevel>,

    /// WebSocket 服务监听端口（可选，不指定则不启动 WebSocket）
    #[arg(long)]
    pub websocket_port: Option<u16>,

    /// Telnet 管理端口（可选，不指定则不启动 Telnet）
    #[arg(long)]
    pub telnet_port: Option<u16>,

    /// Telnet 管理口监听地址（默认 127.0.0.1；仅在 --telnet-port 启用时生效）
    ///
    /// 与主 `--ip` 独立：即使 FTAPI/REST/gRPC 绑定 0.0.0.0，Telnet 默认也
    /// 只监听 loopback，避免误暴露无鉴权管理口。
    #[arg(long)]
    pub telnet_ip: Option<String>,

    /// REST API 监听端口（可选，不指定则不启动 REST API）
    #[arg(long)]
    pub rest_port: Option<u16>,

    /// gRPC 服务监听端口（可选，不指定则不启动 gRPC）
    #[arg(long)]
    pub grpc_port: Option<u16>,

    /// RSA 私钥文件路径（PEM 格式，启用后 InitConnect 使用 RSA 加解密）
    #[arg(long)]
    pub rsa_private_key: Option<String>,

    /// JSON 格式日志
    #[arg(long)]
    pub json_log: bool,

    /// 界面语言 (chs=简体中文, cht=繁体中文, en=英文)
    #[arg(long)]
    pub lang: Option<String>,

    /// 后台自动更新语言包。默认 true；无 endpoint 或下载失败不会阻塞启动。
    ///
    /// endpoint 来源优先级: CLI `--language-pack-endpoint` > TOML/XML
    /// `language_pack_endpoint` > `FUTU_LANGUAGE_PACK_ENDPOINT`。未配置 endpoint
    /// 时状态为 enabled_no_endpoint，不联网。
    #[arg(long, value_name = "BOOL", value_parser = clap::value_parser!(bool))]
    pub language_pack_auto_update: Option<bool>,

    /// 语言包 HTTPS endpoint 或 manifest URL。
    ///
    /// 默认不写死任何内部 endpoint；HTTP 仅允许 localhost 测试。
    #[arg(long, value_name = "URL")]
    pub language_pack_endpoint: Option<String>,

    /// 语言包 cache 根目录；默认按 OS cache dir 或 FUTU_LANGUAGE_PACK_CACHE_DIR。
    #[arg(long, value_name = "DIR")]
    pub language_pack_cache_dir: Option<std::path::PathBuf>,

    /// 语言包后台更新 HTTP 超时，单位毫秒；默认 3000。
    #[arg(long)]
    pub language_pack_update_timeout_ms: Option<u64>,

    /// REST API Bearer Token 鉴权：加载 keys.json（futucli gen-key 生成）
    ///
    /// 不指定时 REST API 只读接口保持 legacy 无鉴权；写交易/admin 仍要求 API key。
    #[arg(long)]
    pub rest_keys_file: Option<std::path::PathBuf>,

    /// gRPC Bearer Token 鉴权：加载 keys.json（futucli gen-key 生成）
    ///
    /// 不指定时 gRPC 无鉴权。通常与 --rest-keys-file 指向同一文件。
    #[arg(long)]
    pub grpc_keys_file: Option<std::path::PathBuf>,

    /// 核心 WebSocket Bearer Token 鉴权：加载 keys.json
    ///
    /// v1.0 起核心 WS（`--websocket-port`，Futu SDK 使用的 binary WS）支持
    /// 握手 + per-message scope 鉴权。客户端用 `?token=<plaintext>` query 或
    /// `Authorization: Bearer <plaintext>` header 传 key。不指定这个 flag 时
    /// WS 无鉴权（legacy 保持兼容，启动 warn）。通常与 `--rest-keys-file` 指向
    /// 同一文件。
    #[arg(long)]
    pub ws_keys_file: Option<std::path::PathBuf>,

    /// v1.4.104 external reviewer S-001 (P0) fix: native TCP (FTAPI port `--port`) 显式
    /// 允许无 auth 接受连接.
    ///
    /// **背景**: native TCP FTAPI 协议 (Python SDK / C++ OpenD 用) 没有
    /// Authorization header 概念, InitConnect proto 无 Bearer 字段. 加 keystore
    /// 后无法做 caller-specific scope 检查.
    ///
    /// **默认行为 (v1.4.104+)**: 配置任一 keys file (`--rest-keys-file` /
    /// `--grpc-keys-file` / `--ws-keys-file`) → daemon **关闭 TCP 端口**
    /// (fail-closed, 防 v1.4.103 external reviewer S-001 跨 surface bypass).
    ///
    /// 显式 opt-in 此 flag → 保留 TCP 端口, daemon 启动 loud warn 用户该
    /// 端口完全无 auth.
    #[arg(long, default_value_t = false)]
    pub allow_tcp_unauthenticated: bool,

    /// 审计日志输出：JSONL 文件路径或目录
    ///
    /// - 带扩展名的路径（如 `/var/log/futu-audit.jsonl`）→ 单文件 append
    /// - 不带扩展名 / 以 `/` 结尾（如 `/var/log/futu-audit/`）→ 每日滚动，
    ///   文件名 `futu-audit.log` + 日期后缀
    ///
    /// 只记录 auth / 交易 事件（target = "futu_audit"），常规日志不受影响。
    #[arg(long)]
    pub audit_log: Option<std::path::PathBuf>,

    /// v1.4.87 #3 G1: 时区覆盖 (IANA name, 如 "Asia/Hong_Kong" / "America/New_York")
    ///
    /// 用于 `hours_window` 限额检查等 "local time" 语义. 不指定时用系统 `TZ`
    /// 环境变量, 仍未设则用 UTC. 典型场景:
    ///
    /// - Daemon 跑在 UTC server 但想 HK 交易时段限额 → `--tz Asia/Hong_Kong`
    /// - Daemon 跑在 local workstation 且 `TZ` 已正确 → 不用 `--tz`
    ///
    /// 优先级: `--tz` flag > `TZ` env var > UTC.
    #[arg(long, value_name = "IANA_TZ")]
    pub tz: Option<String>,

    /// 长跑 daemon: 在 client_sig 到期前 1 小时主动刷新。
    ///
    /// 默认关闭。也可通过环境变量 `FUTU_CLIENT_SIG_PROACTIVE_REFRESH=1` 打开。
    /// 建议先在非关键账户长跑验证后再用于生产。
    #[arg(long, default_value_t = false)]
    pub client_sig_proactive_refresh: bool,

    /// 长跑 daemon: reconnect 连续 TCP 登录失败时尝试刷新 client_sig 后再登录。
    ///
    /// 默认关闭。也可通过环境变量 `FUTU_CLIENT_SIG_REACTIVE_REFRESH=1` 打开。
    /// 该路径只在连续失败达到阈值后触发，避免把瞬时网络抖动当成凭据过期。
    #[arg(long, default_value_t = false)]
    pub client_sig_reactive_refresh: bool,

    /// **DEV-ONLY** v1.4.97 P1-D-C: 每 N 秒强制将 qot_logined 置 false 触发
    /// P1-D self-heal ladder, 给 tester 真机 verify ladder 4 cell 用.
    ///
    /// 仅在 `cargo build --features dev-flags` 编译时可见. release build
    /// (no feature) 不暴露此 flag. 防 production 误启用 (per 坑 #50 SPKI dev
    /// pattern).
    ///
    /// **典型使用** (仅 tester 用):
    /// ```bash
    /// FUTU_QOT_RELOGIN_BACKOFF_MS=5000,10000,20000,40000 \
    ///   futu-opend --inject-auth-failure-every=10 --login-account ...
    /// # 期望日志: P1-D ladder 5s → 10s → 20s → 40s 各 trigger 一次
    /// ```
    #[cfg(feature = "dev-flags")]
    #[arg(long, value_name = "SECONDS", hide = false)]
    pub inject_auth_failure_every: Option<u64>,
}

impl std::fmt::Debug for Args {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let login_account_fp = self
            .login_account
            .as_deref()
            .map(futu_backend::auth::redact::account_log_fingerprint);
        let login_pwd = redact_debug_option(&self.login_pwd);
        let login_pwd_md5 = redact_debug_option(&self.login_pwd_md5);
        let device_id_fp = self
            .device_id
            .as_deref()
            .map(futu_backend::auth::redact::device_id_log_fingerprint);
        let verify_code = redact_debug_option(&self.verify_code);

        let mut debug = f.debug_struct("Args");
        debug
            .field("cfg_file", &self.cfg_file)
            .field("config", &self.config)
            .field("ip", &self.ip)
            .field("port", &self.port)
            .field("login_account_fp", &login_account_fp)
            .field("login_pwd", &login_pwd)
            .field("login_pwd_md5", &login_pwd_md5)
            .field("login_pwd_file", &self.login_pwd_file)
            .field("login_region", &self.login_region)
            .field("platform", &self.platform)
            .field("auth_server", &self.auth_server)
            .field("device_id_fp", &device_id_fp)
            .field("reset_device", &self.reset_device)
            .field("setup_only", &self.setup_only)
            .field("verify_code", &verify_code)
            .field("log_level", &self.log_level)
            .field("websocket_port", &self.websocket_port)
            .field("telnet_port", &self.telnet_port)
            .field("telnet_ip", &self.telnet_ip)
            .field("rest_port", &self.rest_port)
            .field("grpc_port", &self.grpc_port)
            .field("rsa_private_key", &self.rsa_private_key)
            .field("json_log", &self.json_log)
            .field("lang", &self.lang)
            .field("language_pack_auto_update", &self.language_pack_auto_update)
            .field("language_pack_endpoint", &self.language_pack_endpoint)
            .field("language_pack_cache_dir", &self.language_pack_cache_dir)
            .field(
                "language_pack_update_timeout_ms",
                &self.language_pack_update_timeout_ms,
            )
            .field("rest_keys_file", &self.rest_keys_file)
            .field("grpc_keys_file", &self.grpc_keys_file)
            .field("ws_keys_file", &self.ws_keys_file)
            .field("allow_tcp_unauthenticated", &self.allow_tcp_unauthenticated)
            .field("audit_log", &self.audit_log)
            .field("tz", &self.tz)
            .field(
                "client_sig_proactive_refresh",
                &self.client_sig_proactive_refresh,
            )
            .field(
                "client_sig_reactive_refresh",
                &self.client_sig_reactive_refresh,
            );

        #[cfg(feature = "dev-flags")]
        debug.field("inject_auth_failure_every", &self.inject_auth_failure_every);

        debug.finish()
    }
}

fn redact_debug_option(value: &Option<String>) -> String {
    match value {
        Some(value) => format!("<REDACTED len={}>", value.len()),
        None => "<NONE>".to_string(),
    }
}

#[cfg(test)]
mod tests;