futu_rest/

server.rs

//! REST API HTTP 服务
//!
//! 使用 axum 构建，复用 OpenD 的 RequestRouter 处理请求。
//! 支持 WebSocket 推送: 客户端连接 /ws 可接收实时行情和交易推送。

use std::sync::Arc;

mod cors;
mod metrics;
mod probes;
mod startup;

mod generated_routes {
    include!(concat!(env!("OUT_DIR"), "/generated_rest_routes.rs"));
}

use axum::Router;
use axum::body::to_bytes;
use axum::http::{StatusCode, header};
use axum::middleware::Next;
use axum::response::{IntoResponse, Response};
use axum::routing::get;
use futu_auth::{KeyStore, RuntimeCounters};

use futu_server::router::RequestRouter;

use crate::adapter::RestState;
use crate::auth::{AuthState, bearer_auth};
use crate::ws::{self, WsBroadcaster};

use metrics::metrics_handler;
use probes::{health_handler, livez_handler, readyz_handler};
pub use startup::{
    RestTlsConfig, RestTransport, start_with_auth, start_with_auth_and_admin,
    start_with_auth_full_admin, start_with_auth_full_admin_until_shutdown,
    start_with_auth_full_admin_until_shutdown_with_listener_events,
    start_with_auth_full_admin_until_shutdown_with_transport_and_listener_events,
};

/// REST admin/diagnostic extension hooks injected by `futu-opend`.
///
/// These hooks are a single surface-adapter bundle: the REST crate keeps the
/// HTTP routing shape, while `futu-opend` owns the gateway/cache providers.
#[derive(Default)]
pub struct RestAdminHooks {
    pub admin_status_provider: Option<crate::adapter::AdminStatusProvider>,
    pub admin_shutdown_handler: Option<crate::adapter::AdminShutdownHandler>,
    pub admin_reload_handler: Option<crate::adapter::AdminReloadHandler>,
    pub push_health_snapshot_provider: Option<crate::adapter::PushHealthSnapshotProvider>,
    pub card_num_resolver: Option<crate::adapter::CardNumResolver>,
}

/// v1.4.93 P0-5 (NEW-C-02): REST `/ws` legacy mode 的 startup WARN 文本。
///
/// 抽出 const 以便单测验证 warn 消息携带 "v2"/"reject" 等关键提示词，
/// 防止后续被误删（同模式 v1.4.86 SEC-003 Q4 已沉淀）。
pub(crate) const LEGACY_WS_WARN_MESSAGE: &str = "WS endpoint /ws also accepts unauthenticated connections in legacy mode — \
     same posture as REST mutating-blocked: legacy clients may push to /ws without auth. \
     Migrate to --rest-keys-file for production. v2 will default-reject.";

/// 构建 legacy read-only REST API 路由（KeyStore 为空）。
///
/// 这是 crate 内测试/兼容入口：只读 endpoint 保持无鉴权兼容，写交易/admin
/// 仍由 middleware 拦截。生产 daemon 必须走 `build_router_with_auth*` /
/// `start_with_auth_full_admin_until_shutdown`，避免误接无 key legacy 模式。
#[cfg(test)]
pub(crate) fn build_legacy_readonly_router(
    router: Arc<RequestRouter>,
    ws_broadcaster: Arc<WsBroadcaster>,
) -> Router {
    build_router_with_auth(
        router,
        ws_broadcaster,
        Arc::new(KeyStore::empty()),
        Arc::new(RuntimeCounters::new()),
    )
}

/// 构建 REST API 路由，携带 KeyStore 做 Bearer Token 鉴权 + RuntimeCounters 做限额
///
/// `key_store.is_configured() == false` 时等价于 crate-local
/// `build_legacy_readonly_router`（保持旧行为）。
/// `counters` 应由 main 全进程共享：REST / gRPC / MCP 共用一个实例才能保证
/// rate limit / 日累计跨接口一致
pub fn build_router_with_auth(
    router: Arc<RequestRouter>,
    ws_broadcaster: Arc<WsBroadcaster>,
    key_store: Arc<KeyStore>,
    counters: Arc<RuntimeCounters>,
) -> Router {
    build_router_with_auth_and_admin(router, ws_broadcaster, key_store, counters, None)
}

/// v1.4.32+ 扩展：额外传入 admin_status_provider，`/api/admin/status` 用。
/// 旧 `build_router_with_auth` 内部委托到此，`admin_status_provider = None`
/// 时行为与之前完全一致（admin_status endpoint 返 503）。
/// `push_health_snapshot_provider` 同理只在 full-admin hooks 入口注入；
/// 未注入时 `/api/push-subscriber-info` 返 503，避免把 wiring 缺口伪装成
/// `ret_type=0` 的真实健康快照。
pub fn build_router_with_auth_and_admin(
    router: Arc<RequestRouter>,
    ws_broadcaster: Arc<WsBroadcaster>,
    key_store: Arc<KeyStore>,
    counters: Arc<RuntimeCounters>,
    admin_status_provider: Option<crate::adapter::AdminStatusProvider>,
) -> Router {
    build_router_with_auth_full_admin(
        router,
        ws_broadcaster,
        key_store,
        counters,
        RestAdminHooks {
            admin_status_provider,
            ..RestAdminHooks::default()
        },
    )
}

/// v1.4.32+ 完整扩展：同时接 status provider + reload handler。
///
/// v1.4.83 §9 Phase 2 F5: 加 `push_health_snapshot_provider` 参数支持
/// `/api/push-subscriber-info` 返真实 push 通道健康 state。
pub fn build_router_with_auth_full_admin(
    router: Arc<RequestRouter>,
    ws_broadcaster: Arc<WsBroadcaster>,
    key_store: Arc<KeyStore>,
    counters: Arc<RuntimeCounters>,
    hooks: RestAdminHooks,
) -> Router {
    let RestAdminHooks {
        admin_status_provider,
        admin_shutdown_handler,
        admin_reload_handler,
        push_health_snapshot_provider,
        card_num_resolver,
    } = hooks;
    let mut state = RestState::with_auth(
        router,
        ws_broadcaster,
        Arc::clone(&key_store),
        Arc::clone(&counters),
    );
    if let Some(p) = admin_status_provider {
        state = state.with_admin_status_provider(p);
    }
    if let Some(h) = admin_shutdown_handler {
        state = state.with_admin_shutdown_handler(h);
    }
    if let Some(h) = admin_reload_handler {
        state = state.with_admin_reload_handler(h);
    }
    if let Some(p) = push_health_snapshot_provider {
        state = state.with_push_health_snapshot_provider(p);
    }
    if let Some(r) = card_num_resolver {
        state = state.with_card_num_resolver(r);
    }
    let startup_readiness = state.router.startup_readiness();
    let auth_state = AuthState::new(Arc::clone(&key_store), Arc::clone(&counters));

    let cors = cors::build_cors_layer(&key_store);

    let router = Router::new()
        .route("/ws", get(ws::ws_handler))
        .route("/metrics", get(metrics_handler));
    let router = generated_routes::register_generated_routes(router);

    router
        // Inner startup gate for every non-health route already registered:
        // generated /api routes, REST /ws, admin/local routes, and /metrics.
        // Health probes are registered below after this layer and therefore
        // remain callable while authentication is pending.
        .layer(axum::middleware::from_fn_with_state(
            startup_readiness,
            startup_readiness_middleware,
        ))
        // v1.4.93 P0-2 (BUG-002): strict field validation for 7 critical
        // endpoints. Runs AFTER bearer_auth (axum layer ordering: this `.layer()`
        // is added BEFORE `.layer(bearer_auth)` -> strict is INNER -> auth runs
        // first). Pre-auth callers can't probe valid field names. Non-strict
        // paths and non-POST methods pass through unmodified.
        .layer(axum::middleware::from_fn(
            crate::strict_fields::strict_field_validation_middleware,
        ))
        .layer(axum::middleware::from_fn_with_state(
            auth_state,
            bearer_auth,
        ))
        .layer(axum::middleware::from_fn(rest_error_envelope_middleware))
        // `/metrics` + `/livez` + `/health` + `/readyz` 都在 bearer_auth 之外
        // （middleware 只过 /api/*）
        //   - `/metrics`：Prometheus 抓取；handler 内自管三态鉴权
        //     (legacy/public 无 token，scope-mode 要 metrics:read/admin)
        //   - `/livez`：liveness probe —— 进程 alive 就 200
        //   - `/health`：transport health —— Platform/backend connected 才 200
        //   - `/readyz`：readiness probe —— backend connected 且 gateway
        //     dispatch ready 才 200；冷启动/断线期间返 503 避免 LB 打流量进来
        .route("/livez", get(livez_handler))
        .route("/health", get(health_handler))
        .route("/readyz", get(readyz_handler))
        // v1.4.96 BUG #009 sym 4 hotfix (external reviewer double-tester report 2026-04-26):
        // 之前 unmatched /api/foobar 返默认 axum "Not Found" 纯文本, 用户 /
        // LLM agent 完全不知有哪些 endpoint. v1.4.96 加 fallback handler 返
        // JSON + 列出可用 endpoint 类目 + 文档 URL.
        //
        // 注意: scope-mode 下 bearer_auth 已 fail-closed 拦 /api/* 未注册路径
        // 返 404 + JSON. 本 fallback 兜底 legacy mode + non-/api 路径.
        .fallback(unknown_route_fallback)
        .layer(cors)
        .with_state(state)
}

async fn startup_readiness_middleware(
    axum::extract::State(readiness): axum::extract::State<futu_server::identity::StartupReadiness>,
    req: axum::extract::Request,
    next: Next,
) -> Response {
    let snapshot = readiness.snapshot();
    let path = req.uri().path();
    let allowed_prelogin = rest_path_allowed_prelogin(path);
    if snapshot.state == futu_server::identity::StartupState::Ready || allowed_prelogin {
        return next.run(req).await;
    }

    (
        StatusCode::SERVICE_UNAVAILABLE,
        axum::Json(serde_json::json!({
            "ret_type": -1,
            "ret_msg": "gateway authentication is not ready",
            "error": "gateway_not_ready",
            "startup_state": snapshot.state,
            "generation": snapshot.generation,
        })),
    )
        .into_response()
}

fn rest_path_allowed_prelogin(path: &str) -> bool {
    matches!(path, "/api/global-state" | "/api/verification")
}

/// v1.4.96 BUG #009 sym 4 hotfix: 给所有 unmatched 路由返 helpful JSON 404,
/// 列出可用 endpoint 类目 + futuapi.com 文档 URL.
async fn unknown_route_fallback(req: axum::extract::Request) -> impl IntoResponse {
    let path = req.uri().path().to_string();
    let method = req.method().to_string();
    (
        axum::http::StatusCode::NOT_FOUND,
        [(axum::http::header::CONTENT_TYPE, "application/json")],
        axum::Json(serde_json::json!({
            "error": format!("unknown route {method} {path:?}"),
            "hint": "see categories below or full reference at https://www.futuapi.com/reference/rest-api/",
            "categories": {
                "qot (行情)": "/api/quote /api/snapshot /api/kline /api/orderbook /api/ticker /api/option-chain /api/option-quote /api/option-strategy /api/option-strategy-analysis /api/option-strategy-spread /api/history-kline /api/static-info /api/subscribe /api/sub-info /api/market-state /api/capital-flow /api/option-expiration-date /api/warrant /api/ipo-list /api/ipo-calendar /api/financial-calendar /api/financial-calendar-target",
                "trd (交易, scope=acc:read or trade:*)": "/api/accounts /api/funds /api/positions /api/orders /api/order-fills /api/history-orders /api/history-order-fills /api/max-trd-qtys /api/combo-max-trd-qtys /api/margin-ratio /api/order-fee /api/sub-acc-push /api/flow-summary /api/order /api/combo-order /api/modify-order /api/cancel-order /api/cancel-all-order /api/unlock-trade /api/reconfirm-order",
                "tier-m (mobile-driven, v1.4.94+)": "/api/cash-log /api/cash-detail /api/biz-group /api/margin-info /api/account-flag /api/bond-total-asset /api/bond-single-asset /api/bond-position-list /api/bond-answer-state /api/bond-trade-reminder",
                "sys": "/api/global-state /api/user-info /api/quote-rights /api/quote-capability /api/delay-statistics /api/ping /api/push-subscriber-info /api/admin/status (admin scope)",
                "infra": "/livez (liveness) /health (backend transport) /readyz (dispatch readiness) /metrics (Prometheus) /ws (WebSocket push)"
            },
            "method_hint": "most endpoints are POST with JSON body; /api/accounts /api/list-accounts /api/health /api/global-state are GET. Check the doc URL for exact verb."
        })),
    )
}

/// releasegate f18fc66da BUG-RG-001: axum extractor rejections (empty JSON
/// body, missing/invalid Content-Type, malformed body at extractor layer)
/// happen before our route handlers run, so they used to escape as
/// `text/plain`. Normalize those framework-level failures to the same machine
/// envelope used by handler-level validation.
async fn rest_error_envelope_middleware(req: axum::extract::Request, next: Next) -> Response {
    let resp = next.run(req).await;
    let status = resp.status();
    if !matches!(
        status,
        StatusCode::BAD_REQUEST | StatusCode::UNSUPPORTED_MEDIA_TYPE
    ) {
        return resp;
    }
    let content_type = resp
        .headers()
        .get(header::CONTENT_TYPE)
        .and_then(|v| v.to_str().ok())
        .unwrap_or("");
    if !content_type.starts_with("text/plain") {
        return resp;
    }

    let bytes = match to_bytes(resp.into_body(), 64 * 1024).await {
        Ok(bytes) => bytes,
        Err(err) => {
            let msg =
                format!("REST request body parse error: failed to read rejection body: {err}");
            return (
                status,
                axum::Json(serde_json::json!({
                    "ret_type": -1,
                    "ret_msg": msg,
                    "error": msg,
                })),
            )
                .into_response();
        }
    };
    let raw = String::from_utf8_lossy(&bytes);
    let msg = format!("REST request body parse error: {}", raw.trim());
    (
        status,
        axum::Json(serde_json::json!({
            "ret_type": -1,
            "ret_msg": msg,
            "error": msg,
        })),
    )
        .into_response()
}

#[cfg(test)]
mod tests;