hypercall_api/

routes.rs

use axum::{
    extract::DefaultBodyLimit,
    middleware as axum_middleware,
    response::IntoResponse,
    routing::{delete, get, post, put},
    Router,
};
use hypercall_types::{
    API_ROUTE_APPROVE_AGENT, API_ROUTE_BULK_ORDER, API_ROUTE_BULK_ORDER_CLOID,
    API_ROUTE_MARGIN_MODE, API_ROUTE_NOTIFICATIONS_MARK_ALL_READ,
    API_ROUTE_NOTIFICATIONS_MARK_READ, API_ROUTE_ORDER, API_ROUTE_ORDERBOOK, API_ROUTE_ORDERS,
    API_ROUTE_ORDER_CLOID, API_ROUTE_PROFILE_IMAGE, API_ROUTE_PUSH_PREFERENCES,
    API_ROUTE_PUSH_SUBSCRIBE, API_ROUTE_PUSH_UNSUBSCRIBE, API_ROUTE_REVOKE_AGENT,
    API_ROUTE_RFQ_ACCEPT, API_ROUTE_RFQ_REQUEST, API_ROUTE_SETTLEMENT_PAYOUTS,
    API_ROUTE_SETTLEMENT_PAYOUTS_SEEN, API_ROUTE_USERNAME,
};
#[cfg(feature = "api-reference")]
use scalar_api_reference::scalar_html_default;
use std::sync::Arc;
use std::time::Duration;
use tower_http::{
    catch_panic::CatchPanicLayer,
    cors::CorsLayer,
    trace::{self, TraceLayer},
};
use tracing::Level;
#[cfg(feature = "api-reference")]
use utoipa_swagger_ui::SwaggerUi;

use super::{directives, handlers, middleware, websocket};
use crate::rfq::handler_state::RfqHandlerState;
use crate::rfq::qp_ws_state::QpWsState;
use crate::runtime_status::{ReadinessGate, StandbyReplayProgress};

type PromoteSender = Arc<tokio::sync::Mutex<Option<tokio::sync::oneshot::Sender<()>>>>;

pub struct BuildAppParams {
    pub app_state: handlers::AppState,
    pub rate_limit_state: middleware::RateLimitState,
    pub ws_state: websocket::WsState,
    pub qp_ws_state: QpWsState,
    pub rfq_handler_state: RfqHandlerState,
    pub readiness: Arc<dyn ReadinessGate>,
    pub standby_progress: Option<Arc<dyn StandbyReplayProgress>>,
    pub standby_promote: Option<PromoteSender>,
    /// Pre-composed admin router (already merged with the api-owned competition
    /// routes and wrapped in the admin auth layer by the server).
    pub admin_router: Router,
    /// OpenAPI spec served by the live Swagger/Scalar routes. The server merges
    /// `hypercall_admin::admin_openapi()` into the api spec (it cannot be merged
    /// inside this crate without an api -> admin dependency), so the live
    /// `/api-docs/openapi.json` matches the committed spec the exporter produces.
    pub openapi_doc: utoipa::openapi::OpenApi,
}

#[cfg(feature = "otel-tracing")]
fn with_trace_context_layer(app: Router) -> Router {
    // Extract W3C Trace Context from incoming requests for distributed tracing.
    app.layer(axum_middleware::from_fn(
        middleware::trace_context_middleware,
    ))
}

#[cfg(not(feature = "otel-tracing"))]
fn with_trace_context_layer(app: Router) -> Router {
    app
}

/// Handler for Prometheus metrics endpoint.
async fn metrics_handler(
    axum::extract::State(app_state): axum::extract::State<handlers::AppState>,
) -> impl IntoResponse {
    (
        [(
            axum::http::header::CONTENT_TYPE,
            "text/plain; version=0.0.4; charset=utf-8",
        )],
        app_state.metrics_renderer.render_metrics(),
    )
}

pub fn build_app(params: BuildAppParams) -> Router {
    let BuildAppParams {
        app_state,
        rate_limit_state,
        ws_state,
        qp_ws_state,
        rfq_handler_state,
        readiness,
        standby_progress,
        standby_promote,
        admin_router,
        openapi_doc,
    } = params;

    let app = Router::new().merge(public_routes(&app_state, rate_limit_state.clone()));
    #[cfg(feature = "rsm-state")]
    let app = app.merge(rsm_rpc_routes(&app_state));
    let app = app
        .merge(write_routes(&app_state, rate_limit_state))
        .merge(bulk_routes(&app_state))
        .merge(directives_routes(&app_state))
        .merge(market_support_routes(&app_state))
        .merge(websocket_routes(ws_state, qp_ws_state))
        .merge(rfq_routes(rfq_handler_state.clone()))
        .merge(admin_router);

    let app = with_api_reference_routes(app, openapi_doc);
    with_global_layers(app, readiness, standby_progress, standby_promote)
}

fn public_routes(
    app_state: &handlers::AppState,
    rate_limit_state: middleware::RateLimitState,
) -> Router {
    // Public routes (no authentication required)
    // Wallet-scoped read endpoints get rate limiting via api_rate_limit_middleware.
    let rate_limited_public_routes = Router::new()
        .route("/portfolio", get(handlers::account::get_portfolio))
        .route(
            "/portfolio/greeks",
            get(handlers::greeks::get_portfolio_greeks),
        )
        .route("/profile", get(handlers::competition::get_profile))
        .route(
            "/profile/trades",
            get(handlers::competition::get_profile_trades),
        )
        .route(
            "/profile/realized-pnl",
            get(handlers::competition::get_realized_pnl),
        )
        .route(
            "/competitions/leaderboard",
            get(handlers::competition::get_competition_leaderboard),
        )
        .route("/risk/grid", get(handlers::account::get_risk_grid))
        .route("/fills", get(handlers::account::get_fills))
        .route(API_ROUTE_ORDERS, get(handlers::account::get_orders))
        .route(
            "/notifications",
            get(handlers::notifications::list_notifications),
        )
        .route(
            "/historical-pnl",
            get(handlers::historical_pnl::get_historical_pnl),
        )
        .route("/mmp-config", get(handlers::admin::get_mmp_config))
        .route("/user-tier", get(handlers::admin::get_user_tier))
        // Username lookup (public, rate-limited)
        .route(API_ROUTE_USERNAME, get(handlers::username::get_username))
        .layer(axum_middleware::from_fn_with_state(
            rate_limit_state,
            middleware::api_rate_limit_middleware,
        ))
        .with_state(app_state.clone());

    let public_routes = Router::new()
        .route("/trades", get(handlers::account::get_trades))
        .route("/markets", get(handlers::account::get_markets))
        .route("/health", get(handlers::health::health))
        .route("/version", get(handlers::health::version))
        .route("/ready", get(handlers::health::ready))
        .route("/exchange-info", get(handlers::health::exchange_info))
        .route("/standby-ready", get(handlers::health::standby_ready))
        .route("/metrics", get(metrics_handler))
        .route("/instruments", get(handlers::market_data::get_instruments))
        .route(
            "/instrument-specs",
            get(handlers::market_data::get_instrument_specs),
        )
        .route(
            "/gas-provider/:chain_id",
            get(handlers::gas_provider::get_gas_provider),
        )
        .route("/candles", get(handlers::candles::get_candles))
        .route(
            "/options-summary",
            get(handlers::market_data::get_options_summary),
        )
        .route(
            "/expiry-summary",
            get(handlers::market_data::get_expiry_summary),
        )
        .route(
            API_ROUTE_ORDERBOOK,
            get(handlers::options_chain::get_orderbook),
        )
        .route(
            "/historical-theos",
            get(handlers::historical_theos::get_historical_theos),
        )
        .route(
            "/historical-theos/batch",
            get(handlers::historical_theos::get_historical_theos_batch),
        )
        .route(
            "/competitions",
            get(handlers::competition::list_competitions),
        )
        .route(
            "/competitions/:id",
            get(handlers::competition::get_competition),
        )
        // Agent authorization management
        .route(
            API_ROUTE_APPROVE_AGENT,
            post(handlers::agents::approve_agent),
        )
        .route(
            API_ROUTE_REVOKE_AGENT,
            delete(handlers::agents::revoke_agent),
        )
        .route(
            "/authorized-agents",
            get(handlers::agents::get_authorized_agents),
        );

    #[cfg(feature = "faucet")]
    let public_routes = public_routes.route("/faucet", post(handlers::testnet::faucet));

    #[cfg(feature = "test-endpoints")]
    let public_routes = public_routes
        .route("/test/spot-price", post(handlers::testnet::set_spot_price))
        .route("/test/option-iv", post(handlers::testnet::set_option_iv))
        .route(
            "/test/balance-ledger",
            post(handlers::testnet::get_balance_ledger),
        )
        .route(
            "/test/option-deposit",
            post(handlers::testnet::apply_option_deposit),
        )
        .route(
            "/test/cancel-all-orders",
            post(handlers::admin::cancel_all_orders),
        )
        .route(
            "/test/expire-instrument",
            post(handlers::testnet::expire_instrument),
        );

    public_routes
        .merge(rate_limited_public_routes)
        .with_state(app_state.clone())
}

#[cfg(feature = "rsm-state")]
fn rsm_rpc_routes(app_state: &handlers::AppState) -> Router {
    if std::env::var("RSM_RPC_ENABLED")
        .map(|value| value == "true" || value == "1")
        .unwrap_or(false)
    {
        tracing::info!("RSM block JSON-RPC enabled at /rsm/rpc");
        Router::new()
            .route("/rsm/rpc", post(handlers::rsm_rpc::rsm_rpc))
            .with_state(app_state.clone())
    } else {
        tracing::info!("RSM block JSON-RPC disabled (set RSM_RPC_ENABLED=true to enable)");
        Router::new().with_state(app_state.clone())
    }
}

fn write_routes(
    app_state: &handlers::AppState,
    rate_limit_state: middleware::RateLimitState,
) -> Router {
    // Write endpoints (require EIP-712 signature authentication)
    // Middleware order: signature_and_agent_middleware (outer, runs first) -> write_route_rate_limit (inner, runs second)
    Router::new()
        .route(API_ROUTE_ORDER, post(handlers::orders::place_order))
        .route(
            API_ROUTE_ORDER,
            put(handlers::replace_orders::replace_order),
        )
        .route(API_ROUTE_ORDER, delete(handlers::orders::cancel_order))
        .route(
            API_ROUTE_ORDER_CLOID,
            delete(handlers::orders::cancel_order_by_cloid),
        )
        .route(
            API_ROUTE_SETTLEMENT_PAYOUTS_SEEN,
            post(handlers::settlement::mark_settlement_payouts_seen),
        )
        .route("/withdraw/option", post(handlers::account::withdraw_option))
        .route("/withdraw/usdc", post(handlers::account::withdraw_usdc))
        .route(
            API_ROUTE_PROFILE_IMAGE,
            post(handlers::profile_image::set_profile_image)
                .layer(DefaultBodyLimit::max(7_000_000)),
        )
        // MMP (Market Maker Protection) endpoints
        .route("/mmp-config", post(handlers::admin::set_mmp_config))
        .route("/mmp-config", delete(handlers::admin::delete_mmp_config))
        .route("/mmp-config/reset", post(handlers::admin::reset_mmp))
        // User tier management endpoints (admin only)
        .route("/user-tier", post(handlers::admin::set_user_tier))
        .route("/user-tier", delete(handlers::admin::delete_user_tier))
        // Username management endpoints
        .route(API_ROUTE_USERNAME, post(handlers::username::set_username))
        .route(
            API_ROUTE_USERNAME,
            delete(handlers::username::delete_username),
        )
        // Push notification subscription management
        .route(
            API_ROUTE_PUSH_SUBSCRIBE,
            post(handlers::push::push_subscribe),
        )
        .route(
            API_ROUTE_PUSH_UNSUBSCRIBE,
            post(handlers::push::push_unsubscribe),
        )
        .route(
            API_ROUTE_PUSH_PREFERENCES,
            post(handlers::push::push_preferences),
        )
        // Persisted notification feed (mark-read requires signature; list is
        // unsigned-with-wallet-query, registered on the public router above)
        .route(
            API_ROUTE_NOTIFICATIONS_MARK_READ,
            post(handlers::notifications::mark_read),
        )
        .route(
            API_ROUTE_NOTIFICATIONS_MARK_ALL_READ,
            post(handlers::notifications::mark_all_read),
        )
        // Margin mode management (requires zero positions)
        .route(
            API_ROUTE_MARGIN_MODE,
            post(handlers::account::set_margin_mode),
        )
        // Rate limiting layer (runs after signature middleware extracts wallet)
        .layer(axum_middleware::from_fn_with_state(
            rate_limit_state,
            middleware::write_route_rate_limit_middleware,
        ))
        // Signature authentication layer (runs first, sets SignerContext)
        .layer(axum_middleware::from_fn_with_state(
            middleware::SignatureMiddlewareState {
                agent_auth: app_state.agent_auth.clone(),
                auth_failure_recorder: app_state.auth_failure_recorder.clone(),
                signing_chain_id: app_state.runtime_config.signing_chain_id,
            },
            middleware::signature_and_agent_middleware,
        ))
        .with_state(app_state.clone())
}

fn bulk_routes(app_state: &handlers::AppState) -> Router {
    // Bulk order endpoints (handle signature verification internally for each order)
    Router::new()
        .route(
            API_ROUTE_BULK_ORDER,
            post(handlers::bulk_orders::bulk_place_order),
        )
        .route(
            API_ROUTE_BULK_ORDER,
            put(handlers::replace_orders::bulk_replace_order),
        )
        .route(
            API_ROUTE_BULK_ORDER,
            delete(handlers::bulk_orders::bulk_cancel_order),
        )
        .route(
            API_ROUTE_BULK_ORDER_CLOID,
            delete(handlers::bulk_orders::bulk_cancel_order_by_cloid),
        )
        .with_state(app_state.clone())
}

fn directives_routes(app_state: &handlers::AppState) -> Router {
    directives::router()
        .route(
            "/v1/directives/:directive_id",
            get(handlers::directives::get_directive_status),
        )
        .route(
            "/v1/withdrawals",
            get(handlers::directives::get_withdrawal_history),
        )
        .with_state(app_state.clone())
}

fn market_support_routes(app_state: &handlers::AppState) -> Router {
    // Greeks endpoint (public, no auth required)
    let greeks_routes = Router::new()
        .route("/greeks", get(handlers::greeks::get_greeks))
        .with_state(app_state.clone());

    // Liquidation endpoints (public, wallet is passed as query param)
    let liquidation_routes = Router::new()
        .route(
            "/liquidation/status",
            get(handlers::liquidation::get_liquidation_status),
        )
        .route(
            "/liquidation/history",
            get(handlers::liquidation::get_liquidation_history),
        )
        .route(
            "/liquidation/auction/:auction_id",
            get(handlers::liquidation::get_liquidation_auction),
        )
        .with_state(app_state.clone());

    // Settlement payout history endpoint (public, wallet is passed as query param)
    let settlement_routes = Router::new()
        .route(
            API_ROUTE_SETTLEMENT_PAYOUTS,
            get(handlers::settlement::get_settlement_payouts),
        )
        .with_state(app_state.clone());

    Router::new()
        .merge(greeks_routes)
        .merge(liquidation_routes)
        .merge(settlement_routes)
}

fn websocket_routes(ws_state: websocket::WsState, qp_ws_state: QpWsState) -> Router {
    // WebSocket route
    let ws_routes = Router::new()
        .route("/ws", get(websocket::websocket_handler))
        .with_state(ws_state);

    // QP WebSocket route for /ws/quotes
    let qp_ws_routes = Router::new()
        .route("/ws/quotes", get(websocket::rfq::qp_websocket_handler))
        .with_state(qp_ws_state);

    Router::new().merge(ws_routes).merge(qp_ws_routes)
}

fn rfq_routes(rfq_handler_state: RfqHandlerState) -> Router {
    // RFQ routes (public: submit, get status, history).
    // The admin quote-provider routes now live in the `hypercall-admin` crate's
    // `admin_router`, composed at the server root.
    Router::new()
        .route(API_ROUTE_RFQ_REQUEST, post(handlers::rfq::submit_rfq))
        .route(API_ROUTE_RFQ_ACCEPT, post(handlers::rfq::accept_rfq_quote))
        .route("/rfq/:rfq_id", get(handlers::rfq::get_rfq))
        .route("/rfq/history", get(handlers::rfq::get_rfq_history))
        .with_state(rfq_handler_state)
}

#[cfg(feature = "api-reference")]
fn with_api_reference_routes(mut app: Router, openapi_doc: utoipa::openapi::OpenApi) -> Router {
    // These are public docs routes, so always strip the hidden Monitoring/Admin
    // tags here regardless of what the caller passed. This keeps the guarantee
    // local to the public route even though the server already filters.
    let openapi_doc = crate::openapi::filter_hidden_tags(openapi_doc);

    // Always enable Swagger UI. The spec is provided by the server, which merges
    // the admin crate's paths in, so the live spec matches the exporter output.
    tracing::info!("Swagger UI enabled at /swagger-ui");
    app = app.merge(SwaggerUi::new("/swagger-ui").url("/api-docs/openapi.json", openapi_doc));

    // Redirect / and /docs to the hosted API reference
    let docs_redirect =
        || async { axum::response::Redirect::to("https://docs.hypercall.xyz/api-reference") };
    app = app
        .route("/", axum::routing::get(docs_redirect))
        .route("/docs", axum::routing::get(docs_redirect));

    // Scalar API Reference at /scalar
    tracing::info!("Scalar API Reference enabled at /scalar");
    let scalar_config = serde_json::json!({
        "url": "/api-docs/openapi.json",
        "theme": "purple"
    });
    let scalar_html = scalar_html_default(&scalar_config);
    app.route(
        "/scalar",
        axum::routing::get(move || {
            let html = scalar_html.clone();
            async move { axum::response::Html(html) }
        }),
    )
}

#[cfg(not(feature = "api-reference"))]
fn with_api_reference_routes(app: Router, _openapi_doc: utoipa::openapi::OpenApi) -> Router {
    app
}

fn with_global_layers(
    app: Router,
    readiness: Arc<dyn ReadinessGate>,
    standby_progress: Option<Arc<dyn StandbyReplayProgress>>,
    standby_promote: Option<PromoteSender>,
) -> Router {
    let app = app.layer(axum_middleware::from_fn_with_state(
        middleware::ReadinessMiddlewareState::new(readiness, standby_progress, standby_promote),
        middleware::readiness_middleware,
    ));
    let app = with_trace_context_layer(app);

    app.layer(
        TraceLayer::new_for_http()
            .make_span_with(trace::DefaultMakeSpan::new().level(Level::INFO))
            .on_response(trace::DefaultOnResponse::new().level(Level::INFO))
            .on_failure(trace::DefaultOnFailure::new().level(Level::ERROR)),
    )
    .layer(CatchPanicLayer::new())
    .layer(CorsLayer::permissive().max_age(Duration::from_secs(86400)))
}