hypercall_api/handlers/

candles.rs

use std::collections::HashMap;
use std::sync::Arc;

use axum::{
    extract::{FromRef, Query, State},
    http::StatusCode,
    Json,
};
use serde::{Deserialize, Serialize};
use utoipa::{IntoParams, ToSchema};

use super::AppState;
use crate::candles::{
    resolve_candle_coin, validate_candle_time_range, CandleResolution, UnderlyingCandleSource,
    UnderlyingCandlesResponse,
};
use crate::models::ApiResponse;

#[derive(Clone)]
pub struct CandleHandlerState {
    pub candle_source: Arc<dyn UnderlyingCandleSource>,
    pub underlying_to_candle_coin: Arc<HashMap<String, String>>,
}

impl FromRef<AppState> for CandleHandlerState {
    fn from_ref(input: &AppState) -> Self {
        Self {
            candle_source: input.candle_source.clone(),
            underlying_to_candle_coin: input.underlying_to_candle_coin.clone(),
        }
    }
}

/// Query parameters for `/candles`.
///
/// `/candles` is underlying-only. Option instruments must use `/historical-theos`.
#[derive(Debug, Deserialize, IntoParams)]
pub struct CandlesQuery {
    /// Underlying symbol (e.g., "BTC", "ETH")
    #[param(example = "BTC")]
    pub underlying: Option<String>,
    /// Option instrument symbol. No longer supported on `/candles`, use `/historical-theos`.
    #[param(example = "BTC-20260331-100000-C")]
    pub instrument_name: Option<String>,
    /// Candle interval (`1m`, `5m`, `15m`, `1h`, `4h`, `1d`)
    #[param(example = "1m")]
    pub resolution: CandleResolution,
    /// Inclusive start timestamp in milliseconds
    #[param(example = 1710000000000_i64)]
    pub start_time_ms: i64,
    /// Exclusive end timestamp in milliseconds
    #[param(example = 1710003600000_i64)]
    pub end_time_ms: i64,
}

#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
#[serde(untagged)]
pub enum CandlesResponse {
    Underlying(UnderlyingCandlesResponse),
}

#[derive(Debug, Serialize, ToSchema)]
pub struct CandlesApiResponse {
    pub success: bool,
    pub data: Option<CandlesResponse>,
    pub error: Option<String>,
}

fn error_response<T>(
    status: StatusCode,
    message: impl Into<String>,
) -> (StatusCode, Json<ApiResponse<T>>) {
    (status, Json(ApiResponse::error(message.into())))
}

fn parse_underlying(params: &CandlesQuery) -> std::result::Result<String, String> {
    if params
        .instrument_name
        .as_ref()
        .map(|value| !value.trim().is_empty())
        .unwrap_or(false)
    {
        return Err(
            "Option candles are no longer served from /candles; use /historical-theos".to_string(),
        );
    }

    params
        .underlying
        .as_ref()
        .map(|value| value.trim())
        .filter(|value| !value.is_empty())
        .map(|value| value.to_string())
        .ok_or_else(|| "underlying is required".to_string())
}

/// Get historical OHLCV candles for an underlying.
#[utoipa::path(
    get,
    path = "/candles",
    params(CandlesQuery),
    responses(
        (status = 200, description = "Historical underlying candles", body = CandlesApiResponse),
        (status = 400, description = "Invalid query parameters"),
        (status = 502, description = "Upstream candle source failure")
    ),
    tag = "Markets"
)]
pub async fn get_candles(
    State(state): State<CandleHandlerState>,
    Query(params): Query<CandlesQuery>,
) -> Result<Json<ApiResponse<CandlesResponse>>, (StatusCode, Json<ApiResponse<CandlesResponse>>)> {
    validate_candle_time_range(params.start_time_ms, params.end_time_ms)
        .map_err(|error| error_response(StatusCode::BAD_REQUEST, error.to_string()))?;

    let underlying_param = parse_underlying(&params)
        .map_err(|error| error_response(StatusCode::BAD_REQUEST, error))?;

    let (underlying, candle_coin) =
        resolve_candle_coin(&underlying_param, &state.underlying_to_candle_coin)
            .map_err(|error| error_response(StatusCode::BAD_REQUEST, error.to_string()))?;

    let mut candles = state
        .candle_source
        .fetch_candles(
            &candle_coin,
            params.resolution,
            params.start_time_ms,
            params.end_time_ms,
        )
        .await
        .map_err(|error| {
            tracing::error!(
                underlying,
                coin = candle_coin,
                resolution = %params.resolution,
                start_time_ms = params.start_time_ms,
                end_time_ms = params.end_time_ms,
                error = %error,
                "Failed to fetch underlying candles"
            );
            error_response(
                StatusCode::BAD_GATEWAY,
                format!("Failed to fetch candles: {}", error),
            )
        })?;

    candles.sort_by_key(|candle| candle.start_time_ms);

    Ok(Json(ApiResponse::success(CandlesResponse::Underlying(
        UnderlyingCandlesResponse {
            underlying,
            resolution: params.resolution,
            candles,
        },
    ))))
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::candles::{CandleSourceError, UnderlyingCandle};
    use async_trait::async_trait;
    use axum::{body::Body, http::Request, routing::get, Router};
    use tower::ServiceExt;

    #[derive(Clone)]
    struct MockCandleSource {
        candles: Vec<UnderlyingCandle>,
        fail: bool,
    }

    #[async_trait]
    impl UnderlyingCandleSource for MockCandleSource {
        async fn fetch_candles(
            &self,
            _coin: &str,
            _resolution: CandleResolution,
            _start_time_ms: i64,
            _end_time_ms: i64,
        ) -> Result<Vec<UnderlyingCandle>, CandleSourceError> {
            if self.fail {
                return Err(CandleSourceError::Upstream("boom".to_string()));
            }
            Ok(self.candles.clone())
        }
    }

    fn build_router(source: Arc<dyn UnderlyingCandleSource>) -> Router {
        let mut mapping = HashMap::new();
        mapping.insert("BTC".to_string(), "BTC".to_string());

        let state = CandleHandlerState {
            candle_source: source,
            underlying_to_candle_coin: Arc::new(mapping),
        };

        Router::new()
            .route("/candles", get(get_candles))
            .with_state(state)
    }

    #[tokio::test]
    async fn test_get_underlying_candles_success_orders_results() {
        let app = build_router(Arc::new(MockCandleSource {
            candles: vec![
                UnderlyingCandle {
                    start_time_ms: 200,
                    end_time_ms: 300,
                    open: 2.0,
                    high: 3.0,
                    low: 1.0,
                    close: 2.5,
                    volume: 20.0,
                },
                UnderlyingCandle {
                    start_time_ms: 100,
                    end_time_ms: 200,
                    open: 1.0,
                    high: 2.0,
                    low: 0.5,
                    close: 1.5,
                    volume: 10.0,
                },
            ],
            fail: false,
        }));

        let response = app
            .oneshot(
                Request::builder()
                    .uri("/candles?underlying=btc&resolution=1m&start_time_ms=1&end_time_ms=999")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(response.status(), StatusCode::OK);
        let body = axum::body::to_bytes(response.into_body(), usize::MAX)
            .await
            .unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();

        assert_eq!(json["success"], true);
        assert_eq!(json["data"]["underlying"], "BTC");
        assert_eq!(json["data"]["resolution"], "1m");

        let candles = json["data"]["candles"].as_array().unwrap();
        assert_eq!(candles.len(), 2);
        assert_eq!(candles[0]["start_time_ms"], 100);
        assert_eq!(candles[1]["start_time_ms"], 200);
    }

    #[tokio::test]
    async fn test_get_candles_option_selector_rejected() {
        let app = build_router(Arc::new(MockCandleSource {
            candles: vec![],
            fail: false,
        }));

        let response = app
            .oneshot(
                Request::builder()
                    .uri("/candles?instrument_name=BTC-20260331-100000-C&resolution=1m&start_time_ms=1&end_time_ms=999")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(response.status(), StatusCode::BAD_REQUEST);
        let body = axum::body::to_bytes(response.into_body(), usize::MAX)
            .await
            .unwrap();
        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
        assert_eq!(
            json["error"],
            "Option candles are no longer served from /candles; use /historical-theos"
        );
    }

    #[tokio::test]
    async fn test_get_candles_missing_underlying_returns_400() {
        let app = build_router(Arc::new(MockCandleSource {
            candles: vec![],
            fail: false,
        }));

        let response = app
            .oneshot(
                Request::builder()
                    .uri("/candles?resolution=1m&start_time_ms=1&end_time_ms=2")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(response.status(), StatusCode::BAD_REQUEST);
    }

    #[tokio::test]
    async fn test_get_candles_unknown_underlying_returns_400() {
        let app = build_router(Arc::new(MockCandleSource {
            candles: vec![],
            fail: false,
        }));

        let response = app
            .oneshot(
                Request::builder()
                    .uri("/candles?underlying=SOL&resolution=1m&start_time_ms=1&end_time_ms=2")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(response.status(), StatusCode::BAD_REQUEST);
    }

    #[tokio::test]
    async fn test_get_candles_upstream_failure_returns_502() {
        let app = build_router(Arc::new(MockCandleSource {
            candles: vec![],
            fail: true,
        }));

        let response = app
            .oneshot(
                Request::builder()
                    .uri("/candles?underlying=BTC&resolution=1m&start_time_ms=1&end_time_ms=2")
                    .body(Body::empty())
                    .unwrap(),
            )
            .await
            .unwrap();

        assert_eq!(response.status(), StatusCode::BAD_GATEWAY);
    }
}