futu_rest/routes/

admin.rs

//! v1.4.32+ daemon 管理 admin REST API。
//!
//! 由同事 2026-04-18 提议"出问题时快速重置"需求衍生出 3 个 endpoint：
//!
//! - `GET  /api/admin/status`   — 只读健康状态快照（Day 1 已实现）
//! - `POST /api/admin/reload`   — 重刷 auth + 重建 broker 通道 + 清 cipher（Day 3）
//! - `POST /api/admin/shutdown` — 优雅退出（Day 2）
//!
//! 全部要求 `Scope::Admin`（scope 模式下）。legacy 模式默认放行 + 日志 WARN。
//!
//! 为什么只放 REST / CLI 运维面而不是 MCP / gRPC：LLM 或通用 proto
//! requester 不该有 shutdown/reload daemon 的能力，blast radius 太大。
//! 这 3 个 endpoint 是 daemon-local admin surface，没有公开 gateway
//! proto_id，因此也不进入 gRPC generic proto request。
//!
//! ## 运行时上下文（v1.4.106 codex 0554 F4 [P3]）
//!
//! 三个 handler 都跑在 axum async runtime 里 (`#[tokio::main]` + axum
//! `Router::route`). 业务约定:
//!
//! - **`admin_status`**: 调 closure provider 同步生成 snapshot, **完全不
//!   阻塞 tokio runtime** (无 I/O / 无 lock 竞争, 仅几个 Arc clone +
//!   `RwLock::read`). 任意时刻可调.
//! - **`admin_shutdown`**: 同步调用 `futu-opend` 注入的 shutdown handler
//!   广播 daemon shutdown 信号；真正的 surface graceful shutdown / JoinHandle
//!   await / abort fallback 由 opend phase4 统一处理。
//! - **`admin_reload`**: 同步阶段清 cipher + bump cipher_state_version (走
//!   `bridge.reload()`, 已是 sync, 几 µs); 后台阶段 `tokio::spawn` 跑
//!   `refresh_credentials_on_disk` 网络 I/O. **handler 自身 await 的
//!   Future 不含网络 I/O** — closure 只 serialize ReloadReport. ops 通过
//!   `/api/admin/status` 看 `last_reload_refresh` 字段 (Running /
//!   Succeeded / Failed / Skipped / NotApplicable) 监控后台 refresh 进度.
//!
//! 这意味着 `/api/admin/reload` 的 HTTP response 总是 <10ms (sync 阶段的
//! 时间), 不再 hang 几秒等 backend 响应. 之前 v1.4.32 - v1.4.105 的
//! `reload()` async 整段 await 模式被 v1.4.106 F3 拆掉.
//!
//! ## Body 校验 (v1.4.106 codex 0554 F2 [P2])
//!
//! POST `/api/admin/reload` + `/api/admin/shutdown` 无 proto request struct,
//! handler 完全不读 body. 但 `strict_fields` middleware 对这两 path 强制
//! empty-body / `{}` / `null`, 任何 user-supplied 字段返 400 列出 unknown
//! fields. 防 `{"force": true}` / `{"reason": ...}` 之类被 silently 接受
//! (用户以为生效, 实际 server 完全无视) 的 silent-success 反模式.

use axum::extract::{Json, State};
use axum::http::StatusCode;
use serde_json::{Value, json};

use crate::adapter::RestState;

type ApiResult = Result<Json<Value>, (StatusCode, Json<Value>)>;

/// GET /api/admin/status — daemon 健康状态快照
///
/// 响应字段见 `futu_gateway_core::bridge::StatusSnapshot`。provider 未注入时返 503
/// （正常启动路径一定会注入；offline mode 下 bridge 存在但无 auth_result，
/// 此时 login.online=false 而不是 503）。
pub async fn admin_status(State(state): State<RestState>) -> ApiResult {
    match &state.admin_status_provider {
        Some(provider) => Ok(Json(provider())),
        None => Err((
            StatusCode::SERVICE_UNAVAILABLE,
            Json(json!({
                "error": "admin status provider not wired (internal setup bug)"
            })),
        )),
    }
}

/// POST /api/admin/shutdown — 优雅退出
///
/// 返回 200 给客户端前调用 daemon-owned shutdown handler。
///
/// REST crate 不能自己 `process::exit`：那会绕过 opend phase4 已经维护的
/// shutdown 广播、surface JoinHandle await、超时 abort fallback 与日志收口。
///
/// 为什么不做更精细的 drain（等正在执行的 trade 请求完成）：
/// - opend 典型部署在 systemd / Docker 里，shutdown 语义就是"请求 daemon
///   进入统一退出路径，supervisor 按策略决定是否重启"。
/// - 正在执行的 broker trade 请求 client 端自己会超时重试，drain 没明显收益。
/// - 并发场景（例如 LLM 同时 100 个 GetFunds）drain 逻辑复杂度 >> 简单 exit。
///
/// 如果未来真需要 drain：可以加 shutdown flag，listener 进 "拒新收旧" 状态，
/// 等所有 in-flight 完成再 exit（类似 nginx -s quit）。目前不做。
pub async fn admin_shutdown(State(state): State<RestState>) -> ApiResult {
    let Some(handler) = &state.admin_shutdown_handler else {
        return Err((
            StatusCode::SERVICE_UNAVAILABLE,
            Json(json!({
                "error": "admin shutdown handler not wired (internal setup bug)"
            })),
        ));
    };
    if let Err(error) = handler() {
        return Err((
            StatusCode::SERVICE_UNAVAILABLE,
            Json(json!({
                "error": "admin shutdown request failed",
                "detail": error,
            })),
        ));
    }
    Ok(Json(json!({
        "ok": true,
        "shutdown_requested": true,
        "message": "daemon shutdown requested; opend will stop surfaces gracefully"
    })))
}

/// POST /api/admin/reload — 重置 trade cipher 缓存（同步）+ 后台刷 credentials
///
/// **同步阶段**（v1.4.106 codex 0554 F1+F3, response return 前已生效）：
/// - 走 `TrdCache::clear_all_ciphers_and_bump_versions()` 清所有 cipher
///   **同时** bump 各账户的 `cipher_state_version`（v1.4.73 BUG-008 idem
///   cache 失效, 防 stale "cached success" 复活）
/// - 客户端必须重新调 `/api/unlock-trade`（带密码 + 可选 OTP）才能下单
///
/// **后台阶段**（v1.4.106 codex 0554 F3 [P2] tokio::spawn）：
/// - 跑 `refresh_credentials_on_disk` → `remember_login` 刷新磁盘 tgtgt;
///   下次 Platform 断线重连时自动用新 tgtgt
/// - 状态写 `bridge.last_reload_refresh`, ops 通过 `/api/admin/status` 看
///   `last_reload_refresh` 字段（Running / Succeeded / Failed / Skipped /
///   NotApplicable）监控后台 refresh 进度
///
/// 不做的事（设计 scope 边界）：
/// - **不**重跑 HTTP auth（那需要重新持有 login_pwd；opend 启动后就不
///   保留 plaintext 密码）
/// - **不**重建 Platform TCP / broker TCP 连接（心跳退出自然会触发 per-broker
///   reconnect watcher 重建；手动重建需要 `push_cb` 线索，复杂度太高）
/// - **不**重启 daemon 进程（用 `/api/admin/shutdown` + supervisor restart 实现）
///
/// 实际使用场景：用户换了交易密码 / 解锁状态错乱 / 想"重新来过" → 调这个。
///
/// # Request body 校验
///
/// 仅接受 empty / `{}` / `null`（v1.4.106 F2 [P2] strict）。任何 user-supplied
/// 字段返 400 列出 unknown fields（handler 完全不读 body，防 silent-accept）。
pub async fn admin_reload(State(state): State<RestState>) -> ApiResult {
    match &state.admin_reload_handler {
        Some(handler) => {
            // v1.4.34 → v1.4.105: handler 返 Future（refresh_credentials_on_disk
            // 内部 await 网络 I/O, response hang 几秒）.
            // v1.4.106 codex 0554 F3 [P2]: handler 仍返 Future (API 兼容)
            // 但内部不再 await 网络 I/O — `bridge.reload()` 已变 sync, 后台
            // refresh tokio::spawn 派发后立即 return ReloadReport. response
            // 总是 <10ms (sync clear + bump 时间), ops 看 /api/admin/status
            // 监控 refresh 进度.
            let fut = handler();
            Ok(Json(fut.await))
        }
        None => Err((
            StatusCode::SERVICE_UNAVAILABLE,
            Json(json!({
                "error": "admin reload handler not wired (internal setup bug)"
            })),
        )),
    }
}

#[cfg(test)]
mod tests;